magic-editor-x 2.1.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 (117) hide show
  1. package/CHANGELOG.md +125 -0
  2. package/README.md +593 -142
  3. package/bin/magic-editor-x.mjs +190 -0
  4. package/dist/admin/{ConfigurationPage-CK2AbfGW.mjs → ConfigurationPage-BxLHIQdo.mjs} +450 -21
  5. package/dist/admin/{ConfigurationPage-CzsT_dO_.js → ConfigurationPage-C-UktL1x.js} +479 -50
  6. package/dist/admin/ConfirmAction-DuQwvRYi.mjs +125 -0
  7. package/dist/admin/ConfirmAction-zLuIFj8t.js +124 -0
  8. package/dist/admin/{CustomBlocksPage-CvLrsBds.js → CustomBlocksPage-CxcTfdOT.js} +135 -84
  9. package/dist/admin/{CustomBlocksPage-B2A8S5MV.mjs → CustomBlocksPage-D8aMbVXc.mjs} +92 -41
  10. package/dist/admin/DraftSync-BIA8cZgA.js +11 -0
  11. package/dist/admin/DraftSync-CUxOMG-E.mjs +12 -0
  12. package/dist/admin/TemplatesPage-Hn6gyu2l.js +993 -0
  13. package/dist/admin/TemplatesPage-jhYi6Zdf.mjs +993 -0
  14. package/dist/admin/de-1cFMs-4c.mjs +43 -0
  15. package/dist/admin/{de-CkUYGb7U.js → de-2Ie5jy7j.js} +86 -2
  16. package/dist/admin/de-B1X46JJZ.js +453 -0
  17. package/dist/admin/{de-rRIutpYJ.mjs → de-BMY2LBaa.mjs} +86 -2
  18. package/dist/admin/{de-Bt6pYIWi.mjs → de-BUS1hUw0.mjs} +145 -0
  19. package/dist/admin/{de-CVbi685U.js → de-C3AsGauQ.js} +145 -0
  20. package/dist/admin/de-DOiGaTNX.mjs +453 -0
  21. package/dist/admin/de-Dn8athM8.js +43 -0
  22. package/dist/admin/{en-DulOcmXb.js → en-Ah-Cw0Wd.js} +86 -2
  23. package/dist/admin/{en-BX362fTp.js → en-BkEjpC3i.js} +145 -0
  24. package/dist/admin/en-CDg_18Bt.js +453 -0
  25. package/dist/admin/en-CIZ5Ggod.js +43 -0
  26. package/dist/admin/en-CU6UzV4g.mjs +453 -0
  27. package/dist/admin/{en-Puup8TFi.mjs → en-CvFiqti2.mjs} +86 -2
  28. package/dist/admin/en-Dc9y-6n9.mjs +43 -0
  29. package/dist/admin/{en-B_HltUxZ.mjs → en-GCzgS9Aw.mjs} +145 -0
  30. package/dist/admin/es-BCpJmUEM.js +453 -0
  31. package/dist/admin/es-BmfffNM2.mjs +453 -0
  32. package/dist/admin/es-C4IRHV5d.js +43 -0
  33. package/dist/admin/{es-CHHEZi44.js → es-C4pEnDRv.js} +145 -0
  34. package/dist/admin/{es-BoQZC86B.js → es-Cr8JH85N.js} +86 -2
  35. package/dist/admin/es-D2Kw6E4N.mjs +43 -0
  36. package/dist/admin/{es-CrhwOq-5.mjs → es-DHBBZKl2.mjs} +145 -0
  37. package/dist/admin/{es-257SSB7f.mjs → es-DbKHZz5l.mjs} +86 -2
  38. package/dist/admin/fr-BOvvfEH7.mjs +43 -0
  39. package/dist/admin/{fr-B3SL0TBV.js → fr-C2aLSwEu.js} +145 -0
  40. package/dist/admin/{fr-C5rSdKU4.mjs → fr-DQJ_7aq5.mjs} +86 -2
  41. package/dist/admin/fr-DZd2XJP6.mjs +453 -0
  42. package/dist/admin/{fr-5djKfQ3s.mjs → fr-Dvq4xk2e.mjs} +145 -0
  43. package/dist/admin/{fr-HxFcPpv4.js → fr-OJ4VW1kh.js} +86 -2
  44. package/dist/admin/fr-ZcN0yM_2.js +453 -0
  45. package/dist/admin/fr-Zkb8vfjN.js +43 -0
  46. package/dist/admin/index-BHBRr562.js +1940 -0
  47. package/dist/admin/index-CQk1XeNb.mjs +1939 -0
  48. package/dist/admin/index-Cm-fFUhE.js +18908 -0
  49. package/dist/admin/index-XgfwqLfV.mjs +18873 -0
  50. package/dist/admin/index.js +1 -1
  51. package/dist/admin/index.mjs +2 -2
  52. package/dist/admin/pt-1IUyx6ae.js +43 -0
  53. package/dist/admin/{pt-D6UuEtPy.mjs → pt-BSLzA17U.mjs} +86 -2
  54. package/dist/admin/pt-C3UdeIpd.mjs +453 -0
  55. package/dist/admin/pt-CImqDnLB.js +453 -0
  56. package/dist/admin/{pt-BdnY2Cth.mjs → pt-CilDggGF.mjs} +145 -0
  57. package/dist/admin/{pt-Cjn2Sc9k.js → pt-D0I0_JYs.js} +86 -2
  58. package/dist/admin/{pt-EVwCuBUK.js → pt-DX0OAIoL.js} +145 -0
  59. package/dist/admin/pt-etwsg3G4.mjs +43 -0
  60. package/dist/admin/useBreakpoint-D30eNTkF.js +37 -0
  61. package/dist/admin/useBreakpoint-DCfn6pDG.mjs +38 -0
  62. package/dist/admin/useT-CmaeZbCr.mjs +65 -0
  63. package/dist/admin/{useT-91ruePzq.js → useT-D3sM9Zf7.js} +4 -70
  64. package/dist/blocks/index.d.mts +167 -0
  65. package/dist/blocks/index.d.ts +167 -0
  66. package/dist/blocks/index.js +631 -0
  67. package/dist/blocks/index.mjs +609 -0
  68. package/dist/react/index.d.mts +39 -0
  69. package/dist/react/index.d.ts +39 -0
  70. package/dist/react/index.js +2687 -0
  71. package/dist/react/index.mjs +2657 -0
  72. package/dist/render/index.d.mts +201 -0
  73. package/dist/render/index.d.ts +201 -0
  74. package/dist/render/index.js +2918 -0
  75. package/dist/render/index.mjs +2896 -0
  76. package/dist/server/index.js +19400 -4738
  77. package/dist/server/index.mjs +19403 -4741
  78. package/dist/vue/index.d.mts +41 -0
  79. package/dist/vue/index.d.ts +41 -0
  80. package/dist/vue/index.js +2630 -0
  81. package/dist/vue/index.mjs +2610 -0
  82. package/package.json +49 -8
  83. package/schema/magic-editor-x.schema.json +1506 -0
  84. package/types/blocks.d.ts +167 -0
  85. package/types/index.d.ts +338 -0
  86. package/types/react.d.ts +39 -0
  87. package/types/render.d.ts +201 -0
  88. package/types/vue.d.ts +41 -0
  89. package/dist/admin/EditorField-7YCdXx-v.mjs +0 -6829
  90. package/dist/admin/EditorField-BdBCW15Q.js +0 -6864
  91. package/dist/admin/api-CmccMxlN.js +0 -36
  92. package/dist/admin/api-D5CAH0nh.mjs +0 -37
  93. package/dist/admin/de-BHPyA2S-.mjs +0 -103
  94. package/dist/admin/de-DBR893G4.js +0 -13
  95. package/dist/admin/de-RMs-_SCK.js +0 -103
  96. package/dist/admin/de-fBFh09Wl.mjs +0 -13
  97. package/dist/admin/en-BluCStLw.mjs +0 -103
  98. package/dist/admin/en-C81faOHP.js +0 -103
  99. package/dist/admin/en-D9Nfccux.mjs +0 -13
  100. package/dist/admin/en-gueRT44P.js +0 -13
  101. package/dist/admin/es-B0Zy8DVg.mjs +0 -13
  102. package/dist/admin/es-CQRI2Prp.mjs +0 -103
  103. package/dist/admin/es-D1QzY0JW.js +0 -103
  104. package/dist/admin/es-DRGs7meF.js +0 -13
  105. package/dist/admin/fr-B8rdLAIL.js +0 -13
  106. package/dist/admin/fr-Di3R6gOX.mjs +0 -103
  107. package/dist/admin/fr-R3_MbzT5.js +0 -103
  108. package/dist/admin/fr-oiUb2bb_.mjs +0 -13
  109. package/dist/admin/index-0_b1iroK.mjs +0 -156
  110. package/dist/admin/index-6SZLli70.js +0 -155
  111. package/dist/admin/pt-B3Jce6uT.mjs +0 -13
  112. package/dist/admin/pt-BCW1u_Hp.js +0 -103
  113. package/dist/admin/pt-BiWuSBcH.js +0 -13
  114. package/dist/admin/pt-Cr9AL408.mjs +0 -103
  115. package/dist/admin/sanitize-DP5aeU7V.js +0 -597
  116. package/dist/admin/sanitize-jjCot5PM.mjs +0 -596
  117. package/dist/admin/useT-vgY88N_H.mjs +0 -131
@@ -0,0 +1,65 @@
1
+ import { jsxs, jsx } from "react/jsx-runtime";
2
+ import { useId, useCallback } from "react";
3
+ import { Flex, Box, Typography } from "@strapi/design-system";
4
+ import { Page, Layouts } from "@strapi/strapi/admin";
5
+ import { useIntl } from "react-intl";
6
+ import { U as getTranslation } from "./index-CQk1XeNb.mjs";
7
+ const PageShell = ({
8
+ title,
9
+ subtitle,
10
+ primaryAction,
11
+ secondaryAction,
12
+ startActions,
13
+ endActions,
14
+ children
15
+ }) => {
16
+ const id = `mex-page-title-${useId().replace(/:/g, "")}`;
17
+ return /* @__PURE__ */ jsxs(Page.Main, { "aria-labelledby": id, children: [
18
+ /* @__PURE__ */ jsx(Page.Title, { children: title }),
19
+ /* @__PURE__ */ jsx(
20
+ Layouts.Header,
21
+ {
22
+ id,
23
+ title,
24
+ subtitle,
25
+ primaryAction,
26
+ secondaryAction
27
+ }
28
+ ),
29
+ startActions || endActions ? /* @__PURE__ */ jsx(Layouts.Action, { startActions, endActions }) : null,
30
+ /* @__PURE__ */ jsx(Layouts.Content, { children: /* @__PURE__ */ jsx(Flex, { direction: "column", alignItems: "stretch", gap: 6, paddingBottom: 8, minWidth: 0, children }) })
31
+ ] });
32
+ };
33
+ const SectionCard = ({ title, subtitle, action, headingTag = "h2", children }) => /* @__PURE__ */ jsx(
34
+ Box,
35
+ {
36
+ tag: "section",
37
+ background: "neutral0",
38
+ hasRadius: true,
39
+ shadow: "tableShadow",
40
+ padding: { initial: 4, medium: 6 },
41
+ minWidth: 0,
42
+ children: /* @__PURE__ */ jsxs(Flex, { direction: "column", alignItems: "stretch", gap: 4, children: [
43
+ title || action ? /* @__PURE__ */ jsxs(Flex, { justifyContent: "space-between", alignItems: "flex-start", gap: 4, wrap: "wrap", children: [
44
+ /* @__PURE__ */ jsxs(Flex, { direction: "column", alignItems: "flex-start", gap: 1, minWidth: 0, flex: "1 1 24rem", children: [
45
+ /* @__PURE__ */ jsx(Typography, { variant: "delta", tag: headingTag, textColor: "neutral800", children: title }),
46
+ subtitle ? /* @__PURE__ */ jsx(Typography, { variant: "pi", textColor: "neutral600", children: subtitle }) : null
47
+ ] }),
48
+ action ? /* @__PURE__ */ jsx(Flex, { gap: 2, wrap: "wrap", children: action }) : null
49
+ ] }) : null,
50
+ children
51
+ ] })
52
+ }
53
+ );
54
+ const useT = () => {
55
+ const { formatMessage } = useIntl();
56
+ return useCallback(
57
+ (id, defaultMessage, values) => formatMessage({ id: getTranslation(id), defaultMessage }, values),
58
+ [formatMessage]
59
+ );
60
+ };
61
+ export {
62
+ PageShell as P,
63
+ SectionCard as S,
64
+ useT as u
65
+ };
@@ -1,10 +1,10 @@
1
1
  "use strict";
2
2
  const jsxRuntime = require("react/jsx-runtime");
3
- const react = require("react");
3
+ const ReactNamespace = require("react");
4
4
  const designSystem = require("@strapi/design-system");
5
5
  const admin = require("@strapi/strapi/admin");
6
6
  const reactIntl = require("react-intl");
7
- const index = require("./index-6SZLli70.js");
7
+ const index = require("./index-BHBRr562.js");
8
8
  const PageShell = ({
9
9
  title,
10
10
  subtitle,
@@ -14,7 +14,7 @@ const PageShell = ({
14
14
  endActions,
15
15
  children
16
16
  }) => {
17
- const id = `mex-page-title-${react.useId().replace(/:/g, "")}`;
17
+ const id = `mex-page-title-${ReactNamespace.useId().replace(/:/g, "")}`;
18
18
  return /* @__PURE__ */ jsxRuntime.jsxs(admin.Page.Main, { "aria-labelledby": id, children: [
19
19
  /* @__PURE__ */ jsxRuntime.jsx(admin.Page.Title, { children: title }),
20
20
  /* @__PURE__ */ jsxRuntime.jsx(
@@ -52,79 +52,13 @@ const SectionCard = ({ title, subtitle, action, headingTag = "h2", children }) =
52
52
  ] })
53
53
  }
54
54
  );
55
- const canTakeFocus = (el) => Boolean(
56
- el && el.isConnected && typeof el.focus === "function" && !el.disabled && (typeof el.getAttribute !== "function" || el.getAttribute("aria-disabled") !== "true")
57
- );
58
- const pickFocusTarget = (opener, fallback) => {
59
- if (canTakeFocus(opener)) return opener;
60
- if (canTakeFocus(fallback)) return fallback;
61
- return null;
62
- };
63
- const refocusIfLost = (opener, fallback, doc = globalThis.document) => {
64
- if (!doc) return;
65
- const active = doc.activeElement;
66
- if (active && active !== doc.body) return;
67
- const target = pickFocusTarget(opener, fallback);
68
- if (target) target.focus();
69
- };
70
- const ConfirmAction = ({
71
- trigger,
72
- title,
73
- body,
74
- confirmLabel,
75
- onConfirm,
76
- variant = "danger",
77
- disabled = false,
78
- fallbackFocusRef
79
- }) => {
80
- const [open, setOpen] = react.useState(false);
81
- const [busy, setBusy] = react.useState(false);
82
- const triggerRef = react.useRef(null);
83
- const restoreFocus = () => requestAnimationFrame(() => {
84
- const active = document.activeElement;
85
- if (active && active !== document.body) return;
86
- const target = pickFocusTarget(triggerRef.current, fallbackFocusRef && fallbackFocusRef.current);
87
- if (target) target.focus();
88
- });
89
- const onOpenChange = (next) => {
90
- if (busy) return;
91
- setOpen(next);
92
- if (!next) restoreFocus();
93
- };
94
- const confirm = async (event) => {
95
- if (event && typeof event.preventDefault === "function") event.preventDefault();
96
- setBusy(true);
97
- try {
98
- await onConfirm();
99
- setOpen(false);
100
- restoreFocus();
101
- } catch {
102
- } finally {
103
- setBusy(false);
104
- }
105
- };
106
- return /* @__PURE__ */ jsxRuntime.jsxs(designSystem.Dialog.Root, { open, onOpenChange, children: [
107
- /* @__PURE__ */ jsxRuntime.jsx(designSystem.Dialog.Trigger, { ref: triggerRef, disabled, children: trigger }),
108
- /* @__PURE__ */ jsxRuntime.jsx(
109
- admin.ConfirmDialog,
110
- {
111
- title,
112
- variant,
113
- endAction: /* @__PURE__ */ jsxRuntime.jsx(designSystem.Button, { fullWidth: true, variant, onClick: confirm, loading: busy, disabled: busy, children: confirmLabel }),
114
- children: body
115
- }
116
- )
117
- ] });
118
- };
119
55
  const useT = () => {
120
56
  const { formatMessage } = reactIntl.useIntl();
121
- return react.useCallback(
57
+ return ReactNamespace.useCallback(
122
58
  (id, defaultMessage, values) => formatMessage({ id: index.getTranslation(id), defaultMessage }, values),
123
59
  [formatMessage]
124
60
  );
125
61
  };
126
- exports.ConfirmAction = ConfirmAction;
127
62
  exports.PageShell = PageShell;
128
63
  exports.SectionCard = SectionCard;
129
- exports.refocusIfLost = refocusIfLost;
130
64
  exports.useT = useT;
@@ -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/index.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
+ }>;
@@ -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/index.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
+ }>;