magic-editor-x 2.2.0 → 2.3.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 (94) hide show
  1. package/CHANGELOG.md +72 -0
  2. package/README.md +493 -168
  3. package/dist/admin/{ConfigurationPage-3Dir3dAf.mjs → ConfigurationPage-BxLHIQdo.mjs} +450 -21
  4. package/dist/admin/{ConfigurationPage-YvnPnna6.js → ConfigurationPage-C-UktL1x.js} +479 -50
  5. package/dist/admin/ConfirmAction-DuQwvRYi.mjs +125 -0
  6. package/dist/admin/ConfirmAction-zLuIFj8t.js +124 -0
  7. package/dist/admin/{CustomBlocksPage-BiiL2ORG.js → CustomBlocksPage-CxcTfdOT.js} +135 -84
  8. package/dist/admin/{CustomBlocksPage-CR2BaP9O.mjs → CustomBlocksPage-D8aMbVXc.mjs} +92 -41
  9. package/dist/admin/DraftSync-BIA8cZgA.js +11 -0
  10. package/dist/admin/DraftSync-CUxOMG-E.mjs +12 -0
  11. package/dist/admin/TemplatesPage-Hn6gyu2l.js +993 -0
  12. package/dist/admin/TemplatesPage-jhYi6Zdf.mjs +993 -0
  13. package/dist/admin/{de-BmmLBJli.mjs → de-1cFMs-4c.mjs} +2 -0
  14. package/dist/admin/{de-BteRx2iA.js → de-2Ie5jy7j.js} +79 -1
  15. package/dist/admin/{de-62Vxb2iw.js → de-B1X46JJZ.js} +205 -2
  16. package/dist/admin/{de-CFX5atOk.mjs → de-BMY2LBaa.mjs} +79 -1
  17. package/dist/admin/{de-Bt6pYIWi.mjs → de-BUS1hUw0.mjs} +145 -0
  18. package/dist/admin/{de-CVbi685U.js → de-C3AsGauQ.js} +145 -0
  19. package/dist/admin/{de-BVvwSYYO.mjs → de-DOiGaTNX.mjs} +205 -2
  20. package/dist/admin/{de-DaJwN6nk.js → de-Dn8athM8.js} +2 -0
  21. package/dist/admin/{en-CyjAcccB.js → en-Ah-Cw0Wd.js} +79 -1
  22. package/dist/admin/{en-BX362fTp.js → en-BkEjpC3i.js} +145 -0
  23. package/dist/admin/{en-VlkaIzrM.js → en-CDg_18Bt.js} +205 -2
  24. package/dist/admin/{en-Cn78RZs-.js → en-CIZ5Ggod.js} +2 -0
  25. package/dist/admin/{en-Cg2Ak5Cr.mjs → en-CU6UzV4g.mjs} +205 -2
  26. package/dist/admin/{en-ea0tfA5i.mjs → en-CvFiqti2.mjs} +79 -1
  27. package/dist/admin/{en-D7mZWLGp.mjs → en-Dc9y-6n9.mjs} +2 -0
  28. package/dist/admin/{en-B_HltUxZ.mjs → en-GCzgS9Aw.mjs} +145 -0
  29. package/dist/admin/{es-BT9oAcHf.js → es-BCpJmUEM.js} +205 -2
  30. package/dist/admin/{es-C9-cXdb6.mjs → es-BmfffNM2.mjs} +205 -2
  31. package/dist/admin/{es-BmGtLkJD.js → es-C4IRHV5d.js} +2 -0
  32. package/dist/admin/{es-CHHEZi44.js → es-C4pEnDRv.js} +145 -0
  33. package/dist/admin/{es-C8GZFGjv.js → es-Cr8JH85N.js} +79 -1
  34. package/dist/admin/{es-joykG5I9.mjs → es-D2Kw6E4N.mjs} +2 -0
  35. package/dist/admin/{es-CrhwOq-5.mjs → es-DHBBZKl2.mjs} +145 -0
  36. package/dist/admin/{es-CEi_ycX8.mjs → es-DbKHZz5l.mjs} +79 -1
  37. package/dist/admin/{fr-CrzxGe5e.mjs → fr-BOvvfEH7.mjs} +2 -0
  38. package/dist/admin/{fr-B3SL0TBV.js → fr-C2aLSwEu.js} +145 -0
  39. package/dist/admin/{fr-BAMSvQbR.mjs → fr-DQJ_7aq5.mjs} +79 -1
  40. package/dist/admin/{fr-DpU_qiXR.mjs → fr-DZd2XJP6.mjs} +205 -2
  41. package/dist/admin/{fr-5djKfQ3s.mjs → fr-Dvq4xk2e.mjs} +145 -0
  42. package/dist/admin/{fr-oRCJNdeJ.js → fr-OJ4VW1kh.js} +79 -1
  43. package/dist/admin/{fr-D6KJqPWi.js → fr-ZcN0yM_2.js} +205 -2
  44. package/dist/admin/{fr-Ct_uPqxV.js → fr-Zkb8vfjN.js} +2 -0
  45. package/dist/admin/index-BHBRr562.js +1940 -0
  46. package/dist/admin/index-CQk1XeNb.mjs +1939 -0
  47. package/dist/admin/{EditorField-Diq1j8kc.js → index-Cm-fFUhE.js} +13704 -6766
  48. package/dist/admin/{EditorField-B8pyAxPE.mjs → index-XgfwqLfV.mjs} +10203 -3265
  49. package/dist/admin/index.js +1 -1
  50. package/dist/admin/index.mjs +2 -2
  51. package/dist/admin/{pt-chN2jrXl.js → pt-1IUyx6ae.js} +2 -0
  52. package/dist/admin/{pt-CQrfqsCN.mjs → pt-BSLzA17U.mjs} +79 -1
  53. package/dist/admin/{pt-jUqOR7Xh.mjs → pt-C3UdeIpd.mjs} +205 -2
  54. package/dist/admin/{pt-BOrl6x-r.js → pt-CImqDnLB.js} +205 -2
  55. package/dist/admin/{pt-BdnY2Cth.mjs → pt-CilDggGF.mjs} +145 -0
  56. package/dist/admin/{pt-tUeJ2Ywd.js → pt-D0I0_JYs.js} +79 -1
  57. package/dist/admin/{pt-EVwCuBUK.js → pt-DX0OAIoL.js} +145 -0
  58. package/dist/admin/{pt-Ga-4Hsv0.mjs → pt-etwsg3G4.mjs} +2 -0
  59. package/dist/admin/useBreakpoint-D30eNTkF.js +37 -0
  60. package/dist/admin/useBreakpoint-DCfn6pDG.mjs +38 -0
  61. package/dist/admin/useT-CmaeZbCr.mjs +65 -0
  62. package/dist/admin/{useT-BWZ_-Hel.js → useT-D3sM9Zf7.js} +4 -70
  63. package/dist/blocks/index.d.mts +167 -0
  64. package/dist/blocks/index.d.ts +167 -0
  65. package/dist/blocks/index.js +631 -0
  66. package/dist/blocks/index.mjs +609 -0
  67. package/dist/react/index.d.mts +39 -0
  68. package/dist/react/index.d.ts +39 -0
  69. package/dist/react/index.js +2687 -0
  70. package/dist/react/index.mjs +2657 -0
  71. package/dist/render/index.d.mts +131 -5
  72. package/dist/render/index.d.ts +131 -5
  73. package/dist/render/index.js +1679 -181
  74. package/dist/render/index.mjs +1679 -181
  75. package/dist/server/index.js +10645 -3716
  76. package/dist/server/index.mjs +10645 -3716
  77. package/dist/vue/index.d.mts +41 -0
  78. package/dist/vue/index.d.ts +41 -0
  79. package/dist/vue/index.js +2630 -0
  80. package/dist/vue/index.mjs +2610 -0
  81. package/package.json +30 -6
  82. package/schema/magic-editor-x.schema.json +540 -1
  83. package/types/blocks.d.ts +167 -0
  84. package/types/index.d.ts +127 -0
  85. package/types/react.d.ts +39 -0
  86. package/types/render.d.ts +131 -5
  87. package/types/vue.d.ts +41 -0
  88. package/dist/admin/api-Dsq53giv.js +0 -37
  89. package/dist/admin/api-RZ0Fz0BD.mjs +0 -38
  90. package/dist/admin/index-C-lyON1B.mjs +0 -303
  91. package/dist/admin/index-iA0lued_.js +0 -302
  92. package/dist/admin/sanitize-Cb4jvBhj.js +0 -628
  93. package/dist/admin/sanitize-ClkX823p.mjs +0 -627
  94. package/dist/admin/useT-pvHmgBFj.mjs +0 -131
@@ -9,6 +9,8 @@ export interface InternalLinkRef {
9
9
  locale: string | null;
10
10
  /** The href stored when the link was inserted (fallback). */
11
11
  href: string | null;
12
+ /** Present (true) for a mention (`data-mex-mention="true"`, an inline entry reference rendered with class `mex-mention`). */
13
+ mention?: true;
12
14
  }
13
15
 
14
16
  /** Block handed to an override. `data` is cleaned for built-in types and as stored for custom blocks. */
@@ -21,6 +23,41 @@ export interface RenderBlock {
21
23
  children: RenderBlock[];
22
24
  }
23
25
 
26
+ /** Text node of the render tree (escaped on output). */
27
+ export interface RenderTextNode {
28
+ type: 'text';
29
+ value: string;
30
+ }
31
+
32
+ /** Element node of the render tree. Attribute names are lower case; `true` is a boolean attribute. */
33
+ export interface RenderElementNode {
34
+ type: 'element';
35
+ tag: string;
36
+ attrs: Record<string, string | true>;
37
+ children: RenderNode[];
38
+ /**
39
+ * Inline style, only set by the renderer for `object-position` of images
40
+ * with a focal point when `focalPoint: 'style'` is on. Overrides cannot set it.
41
+ */
42
+ style?: { 'object-position'?: string };
43
+ }
44
+
45
+ /**
46
+ * HTML that went through your `sanitizeRaw` (raw blocks, string overrides in a
47
+ * tree). Only with `rawHtml: 'allow'` and `sanitizeRaw`; always the only child
48
+ * of its element.
49
+ */
50
+ export interface RenderRawNode {
51
+ type: 'raw';
52
+ html: string;
53
+ }
54
+
55
+ /** Framework-neutral render node. */
56
+ export type RenderNode = RenderElementNode | RenderTextNode | RenderRawNode;
57
+
58
+ /** What an override may return: a string (HTML), nodes, or undefined/null for the default output. */
59
+ export type OverrideResult = string | RenderNode | Array<RenderNode | string> | null | undefined;
60
+
24
61
  export interface HtmlHelpers {
25
62
  /** Escapes text for HTML. */
26
63
  escape(text: unknown): string;
@@ -30,19 +67,50 @@ export interface HtmlHelpers {
30
67
  text(html: unknown): string;
31
68
  /** Validated URL or ''. */
32
69
  url(value: unknown, schemes?: string[]): string;
33
- /** Renders toggle children. */
70
+ /** Renders toggle children to HTML. */
34
71
  renderChildren(blocks: RenderBlock[]): string;
72
+ /** Element node (attributes and URLs are validated when the override returns it). */
73
+ h(tag: string, attrs?: Record<string, unknown>, children?: unknown): RenderElementNode;
74
+ /** Text node. */
75
+ textNode(value: unknown): RenderTextNode;
76
+ /** Nodes of stored inline HTML (strict parser, links resolved). */
77
+ inlineNodes(html: unknown): RenderNode[];
78
+ /** Nodes of toggle children (keeps per-block components in React/Vue). */
79
+ childNodes(blocks: RenderBlock[]): RenderNode[];
80
+ }
81
+
82
+ /** Code block options (HTML, React, Vue; Markdown and text keep plain fences/text). */
83
+ export interface CodeRenderOptions {
84
+ /**
85
+ * Line numbers: `true` for every code block, `'block'` only for codeFlask
86
+ * blocks saved with line numbers on. Adds `mex-code-lines` to `<pre>` and
87
+ * wraps each line in `<span class="mex-code-line">`; number them with CSS
88
+ * counters. Default false.
89
+ */
90
+ lineNumbers?: boolean | 'block';
91
+ /**
92
+ * Copy button: wraps the block in `<div class="mex-code-block"
93
+ * data-mex-code="copy">` with `<button type="button" class="mex-code-copy"
94
+ * data-mex-copy="code">` and a `role="status"` live region. React and Vue
95
+ * wire it; for plain HTML call `enhanceCodeBlocks()`. Labels: 1 to 80
96
+ * characters.
97
+ */
98
+ copyButton?: boolean | { label?: string; copiedLabel?: string; failedLabel?: string };
35
99
  }
36
100
 
37
101
  export interface RenderOptions {
38
102
  /**
39
- * Per-type output. Return a string to replace the default output of that
40
- * block, or undefined to keep it. HTML overrides are responsible for
41
- * escaping what they output (use the helpers).
103
+ * Per-type output. Return nodes (`helpers.h`, `helpers.inlineNodes`; validated)
104
+ * or a string to replace the default output of that block, or undefined to
105
+ * keep it. A string is HTML: `renderHtml` writes it as it is (the override
106
+ * escapes what it outputs, use the helpers); `renderTree` and the React/Vue
107
+ * components use it only with `rawHtml: 'allow'` + `sanitizeRaw` (as the raw
108
+ * child of `<div class="mex-override">`), otherwise the default output.
109
+ * `renderText`/`renderMarkdown` overrides return text/Markdown.
42
110
  */
43
111
  overrides?: Record<
44
112
  string,
45
- (block: RenderBlock, helpers: HtmlHelpers & Record<string, any>) => string | undefined
113
+ (block: RenderBlock, helpers: HtmlHelpers & Record<string, any>) => OverrideResult
46
114
  >;
47
115
  /**
48
116
  * Resolves internal links at render time, so links follow slug changes.
@@ -60,10 +128,68 @@ export interface RenderOptions {
60
128
  embedHosts?: string[];
61
129
  /** `sizes` attribute for images with Media Library formats. Default '100vw'. */
62
130
  imageSizes?: string;
131
+ /** Code block line numbers and copy button. */
132
+ code?: CodeRenderOptions;
133
+ /**
134
+ * Focal point of images (image blocks and gallery images with `focalPoint`).
135
+ * `'data'` (default, CSP friendly): `data-mex-focal-x`/`data-mex-focal-y`
136
+ * (0..1) on `<img>`. `'style'`: also `style="object-position:X% Y%"`
137
+ * (React/Vue: the `style` prop), for pages whose CSP allows inline styles.
138
+ */
139
+ focalPoint?: 'data' | 'style';
140
+ /**
141
+ * Heading anchors `id="mex-h-<blockId>"` (stable across text edits and
142
+ * locales): `true` on every heading, `false` never (table-of-contents entries
143
+ * are then plain text), default only when the value contains a `toc` block.
144
+ * Markdown has no heading ids: its table-of-contents entries link to the
145
+ * GitHub-style slug of the heading text (`#über-uns`, repeats `-1`, `-2`),
146
+ * which Markdown renderers such as GitHub, markdown-it-anchor and rehype-slug assign.
147
+ */
148
+ headingIds?: boolean;
149
+ /** Table of contents: accessible name of a `toc` block without a title (1 to 80 characters, default 'Table of contents'). */
150
+ toc?: { label?: string };
151
+ /**
152
+ * Code-registered block definitions (`defineBlock` from `magic-editor-x/blocks`):
153
+ * blocks of these types are cleaned by their schema and rendered with their
154
+ * `render`/`text`/`markdown`. Without them such blocks get the neutral
155
+ * rendering. Pass a stable array (compiled once per array). `overrides`
156
+ * still win.
157
+ */
158
+ blocks?: ReadonlyArray<import('../blocks/index.js').BlockDefinition<any>>;
159
+ /**
160
+ * Synced blocks (2.3): the sources of `synced` reference blocks, as a map
161
+ * `{ [ref]: document | blocks }` (object or Map) or a function
162
+ * `(ref) => document | blocks | null`. A reference is replaced by a copy of
163
+ * its source (nested references inside a source are dropped). Without this
164
+ * option, or for an unknown reference, a synced block renders nothing.
165
+ * Content API output (`?mex=`) and GraphQL `…Rendered`/`…Resolved` already
166
+ * come expanded.
167
+ */
168
+ synced?: SyncedSources;
63
169
  }
64
170
 
171
+ /** A synced block source: an Editor.js document or its block array. */
172
+ export type SyncedSource = { blocks: ReadonlyArray<unknown> } | ReadonlyArray<unknown>;
173
+ /** Sources of synced blocks by reference (the source's documentId). */
174
+ export type SyncedSources =
175
+ | Readonly<Record<string, SyncedSource>>
176
+ | ReadonlyMap<string, SyncedSource>
177
+ | ((ref: string) => SyncedSource | null | undefined);
178
+
65
179
  /** Renders a stored value to HTML. Empty or invalid input gives ''. */
66
180
  export function renderHtml(value: unknown, options?: RenderOptions): string;
181
+ /** Renders a stored value to framework-neutral nodes (blocks separated by `\n` text nodes). */
182
+ export function renderTree(value: unknown, options?: RenderOptions): RenderNode[];
183
+ /** Serialises render nodes to HTML (text and attributes escaped, raw nodes as they are). */
184
+ export function serializeNodes(nodes: ReadonlyArray<RenderNode>): string;
185
+ /**
186
+ * Browser helper for plain HTML: wires the code copy buttons below `root`
187
+ * (default `document`) to the Clipboard API. Returns a cleanup function; does
188
+ * nothing without a DOM.
189
+ */
190
+ export function enhanceCodeBlocks(root?: ParentNode): () => void;
191
+ /** Copies text with the Clipboard API; resolves false when unavailable or denied. */
192
+ export function copyText(text: string): Promise<boolean>;
67
193
  /** Renders a stored value to plain text. */
68
194
  export function renderText(value: unknown, options?: RenderOptions): string;
69
195
  /** Renders a stored value to Markdown (CommonMark + GFM tables and task lists). */
@@ -9,6 +9,8 @@ export interface InternalLinkRef {
9
9
  locale: string | null;
10
10
  /** The href stored when the link was inserted (fallback). */
11
11
  href: string | null;
12
+ /** Present (true) for a mention (`data-mex-mention="true"`, an inline entry reference rendered with class `mex-mention`). */
13
+ mention?: true;
12
14
  }
13
15
 
14
16
  /** Block handed to an override. `data` is cleaned for built-in types and as stored for custom blocks. */
@@ -21,6 +23,41 @@ export interface RenderBlock {
21
23
  children: RenderBlock[];
22
24
  }
23
25
 
26
+ /** Text node of the render tree (escaped on output). */
27
+ export interface RenderTextNode {
28
+ type: 'text';
29
+ value: string;
30
+ }
31
+
32
+ /** Element node of the render tree. Attribute names are lower case; `true` is a boolean attribute. */
33
+ export interface RenderElementNode {
34
+ type: 'element';
35
+ tag: string;
36
+ attrs: Record<string, string | true>;
37
+ children: RenderNode[];
38
+ /**
39
+ * Inline style, only set by the renderer for `object-position` of images
40
+ * with a focal point when `focalPoint: 'style'` is on. Overrides cannot set it.
41
+ */
42
+ style?: { 'object-position'?: string };
43
+ }
44
+
45
+ /**
46
+ * HTML that went through your `sanitizeRaw` (raw blocks, string overrides in a
47
+ * tree). Only with `rawHtml: 'allow'` and `sanitizeRaw`; always the only child
48
+ * of its element.
49
+ */
50
+ export interface RenderRawNode {
51
+ type: 'raw';
52
+ html: string;
53
+ }
54
+
55
+ /** Framework-neutral render node. */
56
+ export type RenderNode = RenderElementNode | RenderTextNode | RenderRawNode;
57
+
58
+ /** What an override may return: a string (HTML), nodes, or undefined/null for the default output. */
59
+ export type OverrideResult = string | RenderNode | Array<RenderNode | string> | null | undefined;
60
+
24
61
  export interface HtmlHelpers {
25
62
  /** Escapes text for HTML. */
26
63
  escape(text: unknown): string;
@@ -30,19 +67,50 @@ export interface HtmlHelpers {
30
67
  text(html: unknown): string;
31
68
  /** Validated URL or ''. */
32
69
  url(value: unknown, schemes?: string[]): string;
33
- /** Renders toggle children. */
70
+ /** Renders toggle children to HTML. */
34
71
  renderChildren(blocks: RenderBlock[]): string;
72
+ /** Element node (attributes and URLs are validated when the override returns it). */
73
+ h(tag: string, attrs?: Record<string, unknown>, children?: unknown): RenderElementNode;
74
+ /** Text node. */
75
+ textNode(value: unknown): RenderTextNode;
76
+ /** Nodes of stored inline HTML (strict parser, links resolved). */
77
+ inlineNodes(html: unknown): RenderNode[];
78
+ /** Nodes of toggle children (keeps per-block components in React/Vue). */
79
+ childNodes(blocks: RenderBlock[]): RenderNode[];
80
+ }
81
+
82
+ /** Code block options (HTML, React, Vue; Markdown and text keep plain fences/text). */
83
+ export interface CodeRenderOptions {
84
+ /**
85
+ * Line numbers: `true` for every code block, `'block'` only for codeFlask
86
+ * blocks saved with line numbers on. Adds `mex-code-lines` to `<pre>` and
87
+ * wraps each line in `<span class="mex-code-line">`; number them with CSS
88
+ * counters. Default false.
89
+ */
90
+ lineNumbers?: boolean | 'block';
91
+ /**
92
+ * Copy button: wraps the block in `<div class="mex-code-block"
93
+ * data-mex-code="copy">` with `<button type="button" class="mex-code-copy"
94
+ * data-mex-copy="code">` and a `role="status"` live region. React and Vue
95
+ * wire it; for plain HTML call `enhanceCodeBlocks()`. Labels: 1 to 80
96
+ * characters.
97
+ */
98
+ copyButton?: boolean | { label?: string; copiedLabel?: string; failedLabel?: string };
35
99
  }
36
100
 
37
101
  export interface RenderOptions {
38
102
  /**
39
- * Per-type output. Return a string to replace the default output of that
40
- * block, or undefined to keep it. HTML overrides are responsible for
41
- * escaping what they output (use the helpers).
103
+ * Per-type output. Return nodes (`helpers.h`, `helpers.inlineNodes`; validated)
104
+ * or a string to replace the default output of that block, or undefined to
105
+ * keep it. A string is HTML: `renderHtml` writes it as it is (the override
106
+ * escapes what it outputs, use the helpers); `renderTree` and the React/Vue
107
+ * components use it only with `rawHtml: 'allow'` + `sanitizeRaw` (as the raw
108
+ * child of `<div class="mex-override">`), otherwise the default output.
109
+ * `renderText`/`renderMarkdown` overrides return text/Markdown.
42
110
  */
43
111
  overrides?: Record<
44
112
  string,
45
- (block: RenderBlock, helpers: HtmlHelpers & Record<string, any>) => string | undefined
113
+ (block: RenderBlock, helpers: HtmlHelpers & Record<string, any>) => OverrideResult
46
114
  >;
47
115
  /**
48
116
  * Resolves internal links at render time, so links follow slug changes.
@@ -60,10 +128,68 @@ export interface RenderOptions {
60
128
  embedHosts?: string[];
61
129
  /** `sizes` attribute for images with Media Library formats. Default '100vw'. */
62
130
  imageSizes?: string;
131
+ /** Code block line numbers and copy button. */
132
+ code?: CodeRenderOptions;
133
+ /**
134
+ * Focal point of images (image blocks and gallery images with `focalPoint`).
135
+ * `'data'` (default, CSP friendly): `data-mex-focal-x`/`data-mex-focal-y`
136
+ * (0..1) on `<img>`. `'style'`: also `style="object-position:X% Y%"`
137
+ * (React/Vue: the `style` prop), for pages whose CSP allows inline styles.
138
+ */
139
+ focalPoint?: 'data' | 'style';
140
+ /**
141
+ * Heading anchors `id="mex-h-<blockId>"` (stable across text edits and
142
+ * locales): `true` on every heading, `false` never (table-of-contents entries
143
+ * are then plain text), default only when the value contains a `toc` block.
144
+ * Markdown has no heading ids: its table-of-contents entries link to the
145
+ * GitHub-style slug of the heading text (`#über-uns`, repeats `-1`, `-2`),
146
+ * which Markdown renderers such as GitHub, markdown-it-anchor and rehype-slug assign.
147
+ */
148
+ headingIds?: boolean;
149
+ /** Table of contents: accessible name of a `toc` block without a title (1 to 80 characters, default 'Table of contents'). */
150
+ toc?: { label?: string };
151
+ /**
152
+ * Code-registered block definitions (`defineBlock` from `magic-editor-x/blocks`):
153
+ * blocks of these types are cleaned by their schema and rendered with their
154
+ * `render`/`text`/`markdown`. Without them such blocks get the neutral
155
+ * rendering. Pass a stable array (compiled once per array). `overrides`
156
+ * still win.
157
+ */
158
+ blocks?: ReadonlyArray<import('../blocks/index.js').BlockDefinition<any>>;
159
+ /**
160
+ * Synced blocks (2.3): the sources of `synced` reference blocks, as a map
161
+ * `{ [ref]: document | blocks }` (object or Map) or a function
162
+ * `(ref) => document | blocks | null`. A reference is replaced by a copy of
163
+ * its source (nested references inside a source are dropped). Without this
164
+ * option, or for an unknown reference, a synced block renders nothing.
165
+ * Content API output (`?mex=`) and GraphQL `…Rendered`/`…Resolved` already
166
+ * come expanded.
167
+ */
168
+ synced?: SyncedSources;
63
169
  }
64
170
 
171
+ /** A synced block source: an Editor.js document or its block array. */
172
+ export type SyncedSource = { blocks: ReadonlyArray<unknown> } | ReadonlyArray<unknown>;
173
+ /** Sources of synced blocks by reference (the source's documentId). */
174
+ export type SyncedSources =
175
+ | Readonly<Record<string, SyncedSource>>
176
+ | ReadonlyMap<string, SyncedSource>
177
+ | ((ref: string) => SyncedSource | null | undefined);
178
+
65
179
  /** Renders a stored value to HTML. Empty or invalid input gives ''. */
66
180
  export function renderHtml(value: unknown, options?: RenderOptions): string;
181
+ /** Renders a stored value to framework-neutral nodes (blocks separated by `\n` text nodes). */
182
+ export function renderTree(value: unknown, options?: RenderOptions): RenderNode[];
183
+ /** Serialises render nodes to HTML (text and attributes escaped, raw nodes as they are). */
184
+ export function serializeNodes(nodes: ReadonlyArray<RenderNode>): string;
185
+ /**
186
+ * Browser helper for plain HTML: wires the code copy buttons below `root`
187
+ * (default `document`) to the Clipboard API. Returns a cleanup function; does
188
+ * nothing without a DOM.
189
+ */
190
+ export function enhanceCodeBlocks(root?: ParentNode): () => void;
191
+ /** Copies text with the Clipboard API; resolves false when unavailable or denied. */
192
+ export function copyText(text: string): Promise<boolean>;
67
193
  /** Renders a stored value to plain text. */
68
194
  export function renderText(value: unknown, options?: RenderOptions): string;
69
195
  /** Renders a stored value to Markdown (CommonMark + GFM tables and task lists). */