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.
- package/CHANGELOG.md +72 -0
- package/README.md +493 -168
- package/dist/admin/{ConfigurationPage-3Dir3dAf.mjs → ConfigurationPage-BxLHIQdo.mjs} +450 -21
- package/dist/admin/{ConfigurationPage-YvnPnna6.js → ConfigurationPage-C-UktL1x.js} +479 -50
- package/dist/admin/ConfirmAction-DuQwvRYi.mjs +125 -0
- package/dist/admin/ConfirmAction-zLuIFj8t.js +124 -0
- package/dist/admin/{CustomBlocksPage-BiiL2ORG.js → CustomBlocksPage-CxcTfdOT.js} +135 -84
- package/dist/admin/{CustomBlocksPage-CR2BaP9O.mjs → CustomBlocksPage-D8aMbVXc.mjs} +92 -41
- package/dist/admin/DraftSync-BIA8cZgA.js +11 -0
- package/dist/admin/DraftSync-CUxOMG-E.mjs +12 -0
- package/dist/admin/TemplatesPage-Hn6gyu2l.js +993 -0
- package/dist/admin/TemplatesPage-jhYi6Zdf.mjs +993 -0
- package/dist/admin/{de-BmmLBJli.mjs → de-1cFMs-4c.mjs} +2 -0
- package/dist/admin/{de-BteRx2iA.js → de-2Ie5jy7j.js} +79 -1
- package/dist/admin/{de-62Vxb2iw.js → de-B1X46JJZ.js} +205 -2
- package/dist/admin/{de-CFX5atOk.mjs → de-BMY2LBaa.mjs} +79 -1
- package/dist/admin/{de-Bt6pYIWi.mjs → de-BUS1hUw0.mjs} +145 -0
- package/dist/admin/{de-CVbi685U.js → de-C3AsGauQ.js} +145 -0
- package/dist/admin/{de-BVvwSYYO.mjs → de-DOiGaTNX.mjs} +205 -2
- package/dist/admin/{de-DaJwN6nk.js → de-Dn8athM8.js} +2 -0
- package/dist/admin/{en-CyjAcccB.js → en-Ah-Cw0Wd.js} +79 -1
- package/dist/admin/{en-BX362fTp.js → en-BkEjpC3i.js} +145 -0
- package/dist/admin/{en-VlkaIzrM.js → en-CDg_18Bt.js} +205 -2
- package/dist/admin/{en-Cn78RZs-.js → en-CIZ5Ggod.js} +2 -0
- package/dist/admin/{en-Cg2Ak5Cr.mjs → en-CU6UzV4g.mjs} +205 -2
- package/dist/admin/{en-ea0tfA5i.mjs → en-CvFiqti2.mjs} +79 -1
- package/dist/admin/{en-D7mZWLGp.mjs → en-Dc9y-6n9.mjs} +2 -0
- package/dist/admin/{en-B_HltUxZ.mjs → en-GCzgS9Aw.mjs} +145 -0
- package/dist/admin/{es-BT9oAcHf.js → es-BCpJmUEM.js} +205 -2
- package/dist/admin/{es-C9-cXdb6.mjs → es-BmfffNM2.mjs} +205 -2
- package/dist/admin/{es-BmGtLkJD.js → es-C4IRHV5d.js} +2 -0
- package/dist/admin/{es-CHHEZi44.js → es-C4pEnDRv.js} +145 -0
- package/dist/admin/{es-C8GZFGjv.js → es-Cr8JH85N.js} +79 -1
- package/dist/admin/{es-joykG5I9.mjs → es-D2Kw6E4N.mjs} +2 -0
- package/dist/admin/{es-CrhwOq-5.mjs → es-DHBBZKl2.mjs} +145 -0
- package/dist/admin/{es-CEi_ycX8.mjs → es-DbKHZz5l.mjs} +79 -1
- package/dist/admin/{fr-CrzxGe5e.mjs → fr-BOvvfEH7.mjs} +2 -0
- package/dist/admin/{fr-B3SL0TBV.js → fr-C2aLSwEu.js} +145 -0
- package/dist/admin/{fr-BAMSvQbR.mjs → fr-DQJ_7aq5.mjs} +79 -1
- package/dist/admin/{fr-DpU_qiXR.mjs → fr-DZd2XJP6.mjs} +205 -2
- package/dist/admin/{fr-5djKfQ3s.mjs → fr-Dvq4xk2e.mjs} +145 -0
- package/dist/admin/{fr-oRCJNdeJ.js → fr-OJ4VW1kh.js} +79 -1
- package/dist/admin/{fr-D6KJqPWi.js → fr-ZcN0yM_2.js} +205 -2
- package/dist/admin/{fr-Ct_uPqxV.js → fr-Zkb8vfjN.js} +2 -0
- package/dist/admin/index-BHBRr562.js +1940 -0
- package/dist/admin/index-CQk1XeNb.mjs +1939 -0
- package/dist/admin/{EditorField-Diq1j8kc.js → index-Cm-fFUhE.js} +13704 -6766
- package/dist/admin/{EditorField-B8pyAxPE.mjs → index-XgfwqLfV.mjs} +10203 -3265
- package/dist/admin/index.js +1 -1
- package/dist/admin/index.mjs +2 -2
- package/dist/admin/{pt-chN2jrXl.js → pt-1IUyx6ae.js} +2 -0
- package/dist/admin/{pt-CQrfqsCN.mjs → pt-BSLzA17U.mjs} +79 -1
- package/dist/admin/{pt-jUqOR7Xh.mjs → pt-C3UdeIpd.mjs} +205 -2
- package/dist/admin/{pt-BOrl6x-r.js → pt-CImqDnLB.js} +205 -2
- package/dist/admin/{pt-BdnY2Cth.mjs → pt-CilDggGF.mjs} +145 -0
- package/dist/admin/{pt-tUeJ2Ywd.js → pt-D0I0_JYs.js} +79 -1
- package/dist/admin/{pt-EVwCuBUK.js → pt-DX0OAIoL.js} +145 -0
- package/dist/admin/{pt-Ga-4Hsv0.mjs → pt-etwsg3G4.mjs} +2 -0
- package/dist/admin/useBreakpoint-D30eNTkF.js +37 -0
- package/dist/admin/useBreakpoint-DCfn6pDG.mjs +38 -0
- package/dist/admin/useT-CmaeZbCr.mjs +65 -0
- package/dist/admin/{useT-BWZ_-Hel.js → useT-D3sM9Zf7.js} +4 -70
- package/dist/blocks/index.d.mts +167 -0
- package/dist/blocks/index.d.ts +167 -0
- package/dist/blocks/index.js +631 -0
- package/dist/blocks/index.mjs +609 -0
- package/dist/react/index.d.mts +39 -0
- package/dist/react/index.d.ts +39 -0
- package/dist/react/index.js +2687 -0
- package/dist/react/index.mjs +2657 -0
- package/dist/render/index.d.mts +131 -5
- package/dist/render/index.d.ts +131 -5
- package/dist/render/index.js +1679 -181
- package/dist/render/index.mjs +1679 -181
- package/dist/server/index.js +10645 -3716
- package/dist/server/index.mjs +10645 -3716
- package/dist/vue/index.d.mts +41 -0
- package/dist/vue/index.d.ts +41 -0
- package/dist/vue/index.js +2630 -0
- package/dist/vue/index.mjs +2610 -0
- package/package.json +30 -6
- package/schema/magic-editor-x.schema.json +540 -1
- package/types/blocks.d.ts +167 -0
- package/types/index.d.ts +127 -0
- package/types/react.d.ts +39 -0
- package/types/render.d.ts +131 -5
- package/types/vue.d.ts +41 -0
- package/dist/admin/api-Dsq53giv.js +0 -37
- package/dist/admin/api-RZ0Fz0BD.mjs +0 -38
- package/dist/admin/index-C-lyON1B.mjs +0 -303
- package/dist/admin/index-iA0lued_.js +0 -302
- package/dist/admin/sanitize-Cb4jvBhj.js +0 -628
- package/dist/admin/sanitize-ClkX823p.mjs +0 -627
- package/dist/admin/useT-pvHmgBFj.mjs +0 -131
package/dist/render/index.d.mts
CHANGED
|
@@ -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
|
|
40
|
-
*
|
|
41
|
-
*
|
|
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>) =>
|
|
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). */
|
package/dist/render/index.d.ts
CHANGED
|
@@ -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
|
|
40
|
-
*
|
|
41
|
-
*
|
|
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>) =>
|
|
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). */
|