magic-editor-x 2.2.0 → 2.3.1

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 +85 -0
  2. package/README.md +493 -168
  3. package/dist/admin/{ConfigurationPage-YvnPnna6.js → ConfigurationPage-CFP3lp9p.js} +479 -50
  4. package/dist/admin/{ConfigurationPage-3Dir3dAf.mjs → ConfigurationPage-CYGDLjM7.mjs} +450 -21
  5. package/dist/admin/ConfirmAction-DuQwvRYi.mjs +125 -0
  6. package/dist/admin/ConfirmAction-zLuIFj8t.js +124 -0
  7. package/dist/admin/{CustomBlocksPage-CR2BaP9O.mjs → CustomBlocksPage-B5Q33N-s.mjs} +92 -41
  8. package/dist/admin/{CustomBlocksPage-BiiL2ORG.js → CustomBlocksPage-DzPOSpfn.js} +135 -84
  9. package/dist/admin/DraftSync-BIA8cZgA.js +11 -0
  10. package/dist/admin/DraftSync-CUxOMG-E.mjs +12 -0
  11. package/dist/admin/TemplatesPage-4A8JNO_Z.mjs +993 -0
  12. package/dist/admin/TemplatesPage-BVkgafCK.js +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/{EditorField-Diq1j8kc.js → index-DQVE0ymw.js} +13712 -6767
  46. package/dist/admin/index-DR8sHkTk.js +1940 -0
  47. package/dist/admin/index-My6FjjHB.mjs +1939 -0
  48. package/dist/admin/{EditorField-B8pyAxPE.mjs → index-k8_a5o1A.mjs} +10223 -3278
  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-Cmg1jwwG.mjs +65 -0
  62. package/dist/admin/{useT-BWZ_-Hel.js → useT-DNphiBQR.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
@@ -0,0 +1,167 @@
1
+ /**
2
+ * Custom block SDK (`magic-editor-x/blocks`): one definition per block type
3
+ * for the server, the admin editor tool and the renderers.
4
+ */
5
+
6
+ import type { HtmlHelpers, RenderNode, RenderBlock } from './render.js';
7
+
8
+ export type BlockFieldType = 'text' | 'inline' | 'url' | 'enum' | 'number' | 'boolean' | 'array' | 'object';
9
+
10
+ interface FieldBase {
11
+ /** Human-readable name (JSON Schema `title`, at most 100 characters). */
12
+ label?: string;
13
+ }
14
+ /** Plain text, cut to `max` (default 1000, at most 100000). Rendering escapes it. */
15
+ export interface TextField extends FieldBase {
16
+ type: 'text';
17
+ max?: number;
18
+ multiline?: boolean;
19
+ default?: string;
20
+ }
21
+ /** Inline HTML through the shared inline policy (input cut to `max`, default 10000). */
22
+ export interface InlineField extends FieldBase {
23
+ type: 'inline';
24
+ max?: number;
25
+ default?: string;
26
+ }
27
+ /** URL checked with `sanitizeUrl` (`schemes` default http/https, site-relative allowed unless `relative: false`); '' when not allowed. */
28
+ export interface UrlField extends FieldBase {
29
+ type: 'url';
30
+ schemes?: Array<'http' | 'https' | 'mailto' | 'tel'>;
31
+ relative?: boolean;
32
+ }
33
+ /** One of `values` (1 to 100 strings); invalid values become `default` (first value). */
34
+ export interface EnumField<V extends string = string> extends FieldBase {
35
+ type: 'enum';
36
+ values: readonly V[];
37
+ default?: V;
38
+ }
39
+ /** Finite number in `min..max`; invalid values become `default` (the key is omitted without one). */
40
+ export interface NumberField extends FieldBase {
41
+ type: 'number';
42
+ min?: number;
43
+ max?: number;
44
+ integer?: boolean;
45
+ default?: number;
46
+ }
47
+ export interface BooleanField extends FieldBase {
48
+ type: 'boolean';
49
+ default?: boolean;
50
+ }
51
+ /** At most `max` items (default 50, at most 500); items of another type are dropped. */
52
+ export interface ArrayField extends FieldBase {
53
+ type: 'array';
54
+ items: BlockField;
55
+ max?: number;
56
+ }
57
+ export interface ObjectField extends FieldBase {
58
+ type: 'object';
59
+ fields: BlockSchema;
60
+ }
61
+ export type BlockField =
62
+ TextField | InlineField | UrlField | EnumField | NumberField | BooleanField | ArrayField | ObjectField;
63
+
64
+ /** Field descriptors by key (1 to 50 keys matching `/^[A-Za-z][A-Za-z0-9_]{0,63}$/`, nesting at most 4 levels). */
65
+ export type BlockSchema = Record<string, BlockField>;
66
+
67
+ /** Stored value type of one field. */
68
+ export type FieldValue<F> =
69
+ F extends EnumField<infer V>
70
+ ? V
71
+ : F extends TextField | InlineField | UrlField
72
+ ? string
73
+ : F extends NumberField
74
+ ? number
75
+ : F extends BooleanField
76
+ ? boolean
77
+ : F extends ArrayField
78
+ ? Array<FieldValue<F['items']>>
79
+ : F extends ObjectField
80
+ ? BlockData<F['fields']>
81
+ : unknown;
82
+
83
+ /** Stored `data` of a block with this schema (numbers without a default may be missing). */
84
+ export type BlockData<S extends BlockSchema> = { [K in keyof S]: FieldValue<S[K]> };
85
+
86
+ export interface BlockTextHelpers {
87
+ /** Plain text of inline HTML. */
88
+ text(html: unknown): string;
89
+ }
90
+ export interface BlockMarkdownHelpers extends BlockTextHelpers {
91
+ /** Escapes Markdown punctuation. */
92
+ escape(text: unknown): string;
93
+ /** Markdown of inline HTML (links resolved with `options.links`). */
94
+ inline(html: unknown): string;
95
+ }
96
+
97
+ export interface BlockDefinitionInput<S extends BlockSchema = BlockSchema> {
98
+ /** Block type: `/^[A-Za-z][A-Za-z0-9_-]{1,49}$/`, not a built-in tool name (`RESERVED_BLOCK_NAMES`). */
99
+ name: string;
100
+ /** Integer 1 to 1000000 (default 1); shown in Settings > Custom blocks. */
101
+ version?: number;
102
+ title?: string;
103
+ description?: string;
104
+ schema: S;
105
+ /** Extra cleaning after the schema; its result is cleaned by the schema again. A throw keeps the schema-clean data. */
106
+ sanitize?: (
107
+ data: BlockData<S>,
108
+ helpers: {
109
+ sanitizeUrl(value: unknown, options?: { schemes?: string[]; allowRelative?: boolean }): string;
110
+ }
111
+ ) => BlockData<S>;
112
+ /** Plain text (renderText, search snippets); default: text and inline fields, one per line. */
113
+ text?: (data: BlockData<S>, helpers: BlockTextHelpers) => string;
114
+ /** Markdown (renderMarkdown); escape what you output. Default: text and inline fields as paragraphs. */
115
+ markdown?: (data: BlockData<S>, helpers: BlockMarkdownHelpers) => string;
116
+ /**
117
+ * Render-tree output (HTML, React, Vue): return nodes made with `helpers.h`,
118
+ * `helpers.textNode`, `helpers.inlineNodes` (validated like overrides), `[]`
119
+ * for nothing, or null/undefined for the default rendering. A string is used
120
+ * only with `rawHtml: 'allow'` + `sanitizeRaw`.
121
+ */
122
+ render?: (
123
+ block: RenderBlock & { data: BlockData<S> },
124
+ helpers: HtmlHelpers
125
+ ) => RenderNode | Array<RenderNode | string> | string | null | undefined;
126
+ /** Named presets that include the block (`full` always does). */
127
+ presets?: Array<'article' | 'basic' | 'minimal'>;
128
+ }
129
+
130
+ export type BlockDefinition<S extends BlockSchema = BlockSchema> = Readonly<
131
+ Omit<BlockDefinitionInput<S>, 'version' | 'presets'> & {
132
+ version: number;
133
+ presets: ReadonlyArray<'article' | 'basic' | 'minimal'>;
134
+ }
135
+ >;
136
+
137
+ /** Validates and freezes a definition; throws `BlockDefinitionError` with a clear message. */
138
+ export function defineBlock<const S extends BlockSchema>(
139
+ definition: BlockDefinitionInput<S>
140
+ ): BlockDefinition<S>;
141
+ /** JSON Schema (2020-12) of the block's stored `data`. */
142
+ export function blockJsonSchema(
143
+ definition: BlockDefinition<any> | BlockDefinitionInput<any>
144
+ ): Record<string, unknown>;
145
+ /** Problem with a block name, or null when it can be used. */
146
+ export function blockNameProblem(name: unknown): string | null;
147
+
148
+ export class BlockDefinitionError extends Error {
149
+ name: 'BlockDefinitionError';
150
+ code: 'INVALID_DEFINITION' | 'RESERVED_NAME' | 'NAME_TAKEN' | 'REGISTRY_SEALED';
151
+ }
152
+
153
+ export const BLOCK_FIELD_TYPES: readonly BlockFieldType[];
154
+ export const BLOCK_PRESETS: readonly ['article', 'basic', 'minimal'];
155
+ export const RESERVED_BLOCK_NAMES: readonly string[];
156
+ export const BLOCK_LIMITS: Readonly<{
157
+ maxFields: number;
158
+ maxDepth: number;
159
+ maxText: number;
160
+ defaultText: number;
161
+ defaultInline: number;
162
+ maxItems: number;
163
+ defaultItems: number;
164
+ maxEnumValues: number;
165
+ maxValues: number;
166
+ maxUrl: number;
167
+ }>;
package/types/index.d.ts CHANGED
@@ -100,6 +100,14 @@ export interface ImageFile {
100
100
  size?: number;
101
101
  formats?: Record<string, MediaFormat>;
102
102
  }
103
+ /**
104
+ * Focal point of an image in 0..1 (two decimals) from the top left corner.
105
+ * Media Library formats are resized, not cropped, so it applies to every format.
106
+ */
107
+ export interface FocalPoint {
108
+ x: number;
109
+ y: number;
110
+ }
103
111
  export interface ImageData {
104
112
  file: ImageFile;
105
113
  caption: InlineHtml;
@@ -108,6 +116,7 @@ export interface ImageData {
108
116
  stretched: boolean;
109
117
  /** True when the image is decorative (rendered with an empty alt). */
110
118
  decorative?: boolean;
119
+ focalPoint?: FocalPoint;
111
120
  }
112
121
  export interface SimpleImageData {
113
122
  url: Url;
@@ -120,6 +129,82 @@ export interface SimpleImageData {
120
129
  /** True when the image is decorative (rendered with an empty alt). */
121
130
  decorative?: boolean;
122
131
  }
132
+ export interface GalleryImage {
133
+ /** Media Library image; `alt` is the alternative text of this image. */
134
+ file: ImageFile;
135
+ caption: InlineHtml;
136
+ /** True when the image is decorative (rendered with an empty alt). */
137
+ decorative?: boolean;
138
+ focalPoint?: FocalPoint;
139
+ }
140
+ export interface GalleryData {
141
+ /** At most 50 images. */
142
+ images: GalleryImage[];
143
+ /** Layout hint for frontends. */
144
+ layout: 'grid' | 'carousel';
145
+ /** Columns of the grid layout (1 to 6, hint). */
146
+ columns: number;
147
+ caption: InlineHtml;
148
+ /**
149
+ * Built-in block marker (2.3 writes 1). Tells the built-in block apart from a
150
+ * custom block created before 2.3 under the same name, whose data is kept as is.
151
+ */
152
+ _mex: number;
153
+ }
154
+ /** Media Library file of a video, audio or text track. */
155
+ export interface MediaFile {
156
+ url: Url;
157
+ id?: number | string;
158
+ documentId?: string;
159
+ mime?: string;
160
+ name?: string;
161
+ hash?: string;
162
+ ext?: string;
163
+ width?: number;
164
+ height?: number;
165
+ size?: number;
166
+ }
167
+ /** WebVTT text track from the Media Library. */
168
+ export interface MediaTrack {
169
+ file: MediaFile;
170
+ kind: 'captions' | 'subtitles' | 'descriptions' | 'chapters';
171
+ /** BCP 47 language tag or ''. */
172
+ srclang: string;
173
+ label: string;
174
+ /** At most one track per block is the default. */
175
+ default?: boolean;
176
+ }
177
+ export interface VideoData {
178
+ /** Media Library video (`video/*`). */
179
+ file: MediaFile;
180
+ /** Media Library image shown before playback. */
181
+ poster?: ImageFile;
182
+ title: string;
183
+ caption: InlineHtml;
184
+ loop: boolean;
185
+ muted: boolean;
186
+ /** At most 8 tracks. */
187
+ tracks: MediaTrack[];
188
+ /**
189
+ * Built-in block marker (2.3 writes 1). Tells the built-in block apart from a
190
+ * custom block created before 2.3 under the same name, whose data is kept as is.
191
+ */
192
+ _mex: number;
193
+ }
194
+ export interface AudioData {
195
+ /** Media Library audio (`audio/*`). */
196
+ file: MediaFile;
197
+ title: string;
198
+ caption: InlineHtml;
199
+ loop: boolean;
200
+ /** At most 8 tracks. */
201
+ tracks: MediaTrack[];
202
+ /**
203
+ * Built-in block marker (2.3 writes 1). Tells the built-in block apart from a
204
+ * custom block created before 2.3 under the same name, whose data is kept as is.
205
+ */
206
+ _mex: number;
207
+ }
123
208
  export interface LinkToolData {
124
209
  link: Url;
125
210
  meta: { title: string; description: string; site_name?: string; image?: { url: Url } };
@@ -149,6 +234,36 @@ export interface ButtonData {
149
234
  openInNewTab: boolean;
150
235
  }
151
236
  export type DelimiterData = Record<string, never>;
237
+ /** Table of contents: entries are built from the headings when the content is rendered. */
238
+ export interface TocData {
239
+ /** Plain-text title ('' for none). */
240
+ title: string;
241
+ /** Lowest heading level listed (1 to 6, at most `maxLevel`). */
242
+ minLevel: number;
243
+ /** Highest heading level listed (1 to 6). */
244
+ maxLevel: number;
245
+ style: 'ordered' | 'unordered';
246
+ /**
247
+ * Built-in block marker (2.3 writes 1). Tells the built-in block apart from a
248
+ * custom block created before 2.3 under the same name, whose data is kept as is.
249
+ */
250
+ _mex: number;
251
+ }
252
+
253
+ /**
254
+ * Synced block (2.3): a reference to shared content (a Settings > Templates
255
+ * source of kind `synced`). Only the reference is stored; `?mex=` output,
256
+ * GraphQL `…Rendered`/`…Resolved` and the renderers (`options.synced`) expand it.
257
+ */
258
+ export interface SyncedData {
259
+ /** documentId of the source ('' when invalid). */
260
+ ref: string;
261
+ /**
262
+ * Built-in block marker (2.3 writes 1). Tells the built-in block apart from a
263
+ * custom block created before 2.3 under the same name, whose data is kept as is.
264
+ */
265
+ _mex: number;
266
+ }
152
267
 
153
268
  /** Data per built-in block type. */
154
269
  export interface BlockDataMap {
@@ -166,12 +281,17 @@ export interface BlockDataMap {
166
281
  table: TableData;
167
282
  image: ImageData;
168
283
  simpleImage: SimpleImageData;
284
+ gallery: GalleryData;
285
+ video: VideoData;
286
+ audio: AudioData;
169
287
  linkTool: LinkToolData;
170
288
  attaches: AttachesData;
171
289
  embed: EmbedData;
172
290
  personality: PersonalityData;
173
291
  button: ButtonData;
174
292
  delimiter: DelimiterData;
293
+ toc: TocData;
294
+ synced: SyncedData;
175
295
  }
176
296
 
177
297
  export type BuiltInBlockType = keyof BlockDataMap;
@@ -205,7 +325,14 @@ export type {
205
325
  InternalLinkRef,
206
326
  RenderBlock,
207
327
  HtmlHelpers,
328
+ RenderNode,
329
+ RenderElementNode,
330
+ RenderTextNode,
331
+ RenderRawNode,
332
+ CodeRenderOptions,
333
+ OverrideResult,
208
334
  renderHtml,
335
+ renderTree,
209
336
  renderText,
210
337
  renderMarkdown,
211
338
  } from './render.js';
@@ -0,0 +1,39 @@
1
+ /** Types of `magic-editor-x/react` (React 18 and 19; needs `@types/react` for TypeScript). */
2
+
3
+ import type { ComponentType, ReactElement, ReactNode } from 'react';
4
+ import type { RenderBlock, RenderNode, RenderOptions } from './render.js';
5
+
6
+ /** Helpers handed to a block component. */
7
+ export interface ReactBlockHelpers {
8
+ /** Plain text of stored inline HTML. */
9
+ text(html: unknown): string;
10
+ /** Validated URL or ''. */
11
+ url(value: unknown, schemes?: string[]): string;
12
+ /** React nodes of stored inline HTML (strict parser, links resolved). */
13
+ inline(html: unknown): ReactNode[];
14
+ /** React nodes of child blocks (toggle content), with your components applied. */
15
+ renderBlocks(blocks: RenderBlock[]): ReactNode[];
16
+ }
17
+
18
+ /** Props of a block component in `components`. */
19
+ export interface BlockComponentProps {
20
+ block: RenderBlock;
21
+ helpers: ReactBlockHelpers;
22
+ /** The default output of the block. */
23
+ children: ReactNode[];
24
+ }
25
+
26
+ export interface MagicEditorXContentProps {
27
+ /** Stored field value (object, JSON string, 1.x shapes). null renders nothing. */
28
+ value: unknown;
29
+ /** Render options (links, media, embedHosts, imageSizes, code, rawHtml + sanitizeRaw, overrides). */
30
+ options?: RenderOptions;
31
+ /** Per-type components; return null to hide a block. */
32
+ components?: Record<string, ComponentType<BlockComponentProps>>;
33
+ }
34
+
35
+ /** Renders stored content as React elements (a fragment, no wrapper element). */
36
+ export declare function MagicEditorXContent(props: MagicEditorXContentProps): ReactElement;
37
+ /** React nodes of a `renderTree` result. */
38
+ export declare function treeToReact(nodes: RenderNode[]): ReactNode[];
39
+ export default MagicEditorXContent;
package/types/render.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 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.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/types/vue.d.ts ADDED
@@ -0,0 +1,41 @@
1
+ /** Types of `magic-editor-x/vue` (Vue 3.3+). */
2
+
3
+ import type { Component, DefineComponent, VNodeChild } from 'vue';
4
+ import type { RenderBlock, RenderNode, RenderOptions } from './render.js';
5
+
6
+ /** Helpers handed to a block slot or component. */
7
+ export interface VueBlockHelpers {
8
+ /** Plain text of stored inline HTML. */
9
+ text(html: unknown): string;
10
+ /** Validated URL or ''. */
11
+ url(value: unknown, schemes?: string[]): string;
12
+ /** Vnodes of stored inline HTML (strict parser, links resolved). */
13
+ inline(html: unknown): VNodeChild[];
14
+ /** Vnodes of child blocks (toggle content), with your slots/components applied. */
15
+ renderBlocks(blocks: RenderBlock[]): VNodeChild[];
16
+ }
17
+
18
+ /** Props of a `block-<type>` scoped slot. */
19
+ export interface BlockSlotProps {
20
+ block: RenderBlock;
21
+ helpers: VueBlockHelpers;
22
+ /** The default output of the block. */
23
+ children: VNodeChild[];
24
+ }
25
+
26
+ /**
27
+ * Renders stored content. Overrides: scoped slots `block-<type>` or the
28
+ * `components` prop (components declare the props `block` and `helpers` and
29
+ * get the default output in their default slot).
30
+ */
31
+ export declare const MagicEditorXContent: DefineComponent<{
32
+ /** Stored field value (object, JSON string, 1.x shapes). null renders nothing. */
33
+ value?: unknown;
34
+ /** Render options (links, media, embedHosts, imageSizes, code, rawHtml + sanitizeRaw, overrides). */
35
+ options?: RenderOptions;
36
+ /** Per-type components (declare the props `block` and `helpers`). */
37
+ components?: Record<string, Component>;
38
+ }>;
39
+ /** Vnodes of a `renderTree` result. */
40
+ export declare function treeToVue(nodes: RenderNode[]): VNodeChild[];
41
+ export default MagicEditorXContent;
@@ -1,37 +0,0 @@
1
- "use strict";
2
- const API = {
3
- config: "/magic-editor-x/config",
4
- link: "/magic-editor-x/link",
5
- imageByFile: "/magic-editor-x/image/byFile",
6
- imageByUrl: "/magic-editor-x/image/byUrl",
7
- fileUpload: "/magic-editor-x/file/upload",
8
- contentTypes: "/magic-editor-x/content-types",
9
- linkTypes: "/magic-editor-x/links/types",
10
- linkSearch: "/magic-editor-x/links/search",
11
- qualityLinks: "/magic-editor-x/quality/links",
12
- customBlocks: "/magic-editor-x/custom-blocks",
13
- customBlocksExport: "/magic-editor-x/custom-blocks/export",
14
- customBlocksImport: "/magic-editor-x/custom-blocks/import",
15
- customBlocksOrder: "/magic-editor-x/custom-blocks/order",
16
- customBlock: (id) => `/magic-editor-x/custom-blocks/${encodeURIComponent(id)}`,
17
- customBlockDuplicate: (id) => `/magic-editor-x/custom-blocks/${encodeURIComponent(id)}/duplicate`,
18
- collaborationSession: "/magic-editor-x/collaboration/session",
19
- history: "/magic-editor-x/history",
20
- historyItem: (id) => `/magic-editor-x/history/${encodeURIComponent(id)}`,
21
- ai: (action) => `/magic-editor-x/ai/${encodeURIComponent(action)}`,
22
- settings: "/magic-editor-x/settings",
23
- settingsAiTest: "/magic-editor-x/settings/ai/test"
24
- };
25
- const readApiError = (error) => {
26
- const response = error && error.response;
27
- const body = response && response.data;
28
- const apiError = body && body.error;
29
- return {
30
- status: response && response.status || null,
31
- message: apiError && apiError.message || body && body.message || null,
32
- code: apiError && apiError.details && apiError.details.code || null,
33
- details: apiError && apiError.details || null
34
- };
35
- };
36
- exports.API = API;
37
- exports.readApiError = readApiError;
@@ -1,38 +0,0 @@
1
- const API = {
2
- config: "/magic-editor-x/config",
3
- link: "/magic-editor-x/link",
4
- imageByFile: "/magic-editor-x/image/byFile",
5
- imageByUrl: "/magic-editor-x/image/byUrl",
6
- fileUpload: "/magic-editor-x/file/upload",
7
- contentTypes: "/magic-editor-x/content-types",
8
- linkTypes: "/magic-editor-x/links/types",
9
- linkSearch: "/magic-editor-x/links/search",
10
- qualityLinks: "/magic-editor-x/quality/links",
11
- customBlocks: "/magic-editor-x/custom-blocks",
12
- customBlocksExport: "/magic-editor-x/custom-blocks/export",
13
- customBlocksImport: "/magic-editor-x/custom-blocks/import",
14
- customBlocksOrder: "/magic-editor-x/custom-blocks/order",
15
- customBlock: (id) => `/magic-editor-x/custom-blocks/${encodeURIComponent(id)}`,
16
- customBlockDuplicate: (id) => `/magic-editor-x/custom-blocks/${encodeURIComponent(id)}/duplicate`,
17
- collaborationSession: "/magic-editor-x/collaboration/session",
18
- history: "/magic-editor-x/history",
19
- historyItem: (id) => `/magic-editor-x/history/${encodeURIComponent(id)}`,
20
- ai: (action) => `/magic-editor-x/ai/${encodeURIComponent(action)}`,
21
- settings: "/magic-editor-x/settings",
22
- settingsAiTest: "/magic-editor-x/settings/ai/test"
23
- };
24
- const readApiError = (error) => {
25
- const response = error && error.response;
26
- const body = response && response.data;
27
- const apiError = body && body.error;
28
- return {
29
- status: response && response.status || null,
30
- message: apiError && apiError.message || body && body.message || null,
31
- code: apiError && apiError.details && apiError.details.code || null,
32
- details: apiError && apiError.details || null
33
- };
34
- };
35
- export {
36
- API as A,
37
- readApiError as r
38
- };