@unlayer/react-elements 0.1.16 → 0.1.18
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/README.md +45 -1
- package/dist/index.cjs +288 -57
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +153 -18
- package/dist/index.d.ts +153 -18
- package/dist/index.js +287 -58
- package/dist/index.js.map +1 -1
- package/package.json +3 -1
package/dist/index.d.cts
CHANGED
|
@@ -118,6 +118,8 @@ interface MenuItem {
|
|
|
118
118
|
type RenderMode = "web" | "email" | "document";
|
|
119
119
|
interface DesignContent {
|
|
120
120
|
type: string;
|
|
121
|
+
/** Custom tool name — present when `type` is "custom" */
|
|
122
|
+
slug?: string;
|
|
121
123
|
values: Record<string, any>;
|
|
122
124
|
}
|
|
123
125
|
interface DesignColumn {
|
|
@@ -312,6 +314,10 @@ interface BaseItemComponentProps {
|
|
|
312
314
|
* string ("10px", "16px 24px"). Applied by the containing Column. */
|
|
313
315
|
containerPadding?: SizeInput;
|
|
314
316
|
index?: number;
|
|
317
|
+
/** @internal — content id allocated by the containing Column; keeps the
|
|
318
|
+
* value-level _meta.htmlID unique per instance and aligned with the
|
|
319
|
+
* wrapper id and head/json numbering. */
|
|
320
|
+
_metaHtmlId?: string;
|
|
315
321
|
colIndex?: number;
|
|
316
322
|
cells?: any[];
|
|
317
323
|
bodyValues?: any;
|
|
@@ -826,32 +832,54 @@ declare const UnlayerProvider: React__default.FC<UnlayerProviderProps>;
|
|
|
826
832
|
declare function useUnlayerConfig(): UnlayerConfig;
|
|
827
833
|
|
|
828
834
|
/**
|
|
829
|
-
*
|
|
835
|
+
* Options for renderToHtml — config overrides plus document-level extras.
|
|
836
|
+
*/
|
|
837
|
+
interface RenderToHtmlOptions extends Partial<UnlayerConfig> {
|
|
838
|
+
/** Document `<title>` */
|
|
839
|
+
title?: string;
|
|
840
|
+
/**
|
|
841
|
+
* Web-font stylesheets to load via `<link rel="stylesheet">` tags.
|
|
842
|
+
* Elements has no font registry, so pass the URLs for any non-system
|
|
843
|
+
* fonts your design uses (e.g. Google Fonts CSS URLs).
|
|
844
|
+
*/
|
|
845
|
+
fonts?: Array<{
|
|
846
|
+
url: string;
|
|
847
|
+
}>;
|
|
848
|
+
}
|
|
849
|
+
/**
|
|
850
|
+
* Renders an Unlayer element tree to a complete HTML document — from
|
|
851
|
+
* `<!DOCTYPE ...>` to `</html>` — matching the editor's exportHtml layouts.
|
|
830
852
|
*
|
|
831
|
-
* -
|
|
832
|
-
* -
|
|
833
|
-
*
|
|
853
|
+
* Per-mode document shells (mirroring the editor's layout templates):
|
|
854
|
+
* - `email`: XHTML transitional doctype, VML/Office namespaces, and the MSO
|
|
855
|
+
* conditional comments Outlook needs
|
|
856
|
+
* - `web`: HTML5 doctype with standard viewport/charset meta tags
|
|
857
|
+
* - `document`: XHTML transitional doctype for print/PDF pipelines
|
|
834
858
|
*
|
|
835
|
-
* @
|
|
836
|
-
*
|
|
837
|
-
*
|
|
859
|
+
* Use {@link renderToHtmlParts} instead when your app owns the document
|
|
860
|
+
* shell and only needs the head/body chunks.
|
|
861
|
+
*
|
|
862
|
+
* @param element - A React element tree (e.g. `<Email><Row>...</Row></Email>`)
|
|
863
|
+
* @param options - Config overrides (mode, cdnBaseUrl, etc.) plus `title` and `fonts`
|
|
864
|
+
* @returns Complete HTML document string
|
|
838
865
|
* @throws {Error} If rendering fails, with a helpful message
|
|
839
866
|
*
|
|
840
867
|
* @example
|
|
841
868
|
* ```tsx
|
|
842
|
-
* import { renderToHtml,
|
|
869
|
+
* import { renderToHtml, Email, Row, Column, Paragraph } from "@unlayer/react-elements";
|
|
843
870
|
*
|
|
844
871
|
* const html = renderToHtml(
|
|
845
|
-
* <
|
|
846
|
-
* {
|
|
872
|
+
* <Email><Row><Column><Paragraph>Hello</Paragraph></Column></Row></Email>,
|
|
873
|
+
* { title: "Welcome" }
|
|
847
874
|
* );
|
|
875
|
+
* // "<!DOCTYPE HTML PUBLIC ...><html ...>...</html>"
|
|
848
876
|
* ```
|
|
849
877
|
*/
|
|
850
|
-
declare function renderToHtml(element: React__default.ReactElement,
|
|
878
|
+
declare function renderToHtml(element: React__default.ReactElement, options?: RenderToHtmlOptions): string;
|
|
851
879
|
/**
|
|
852
880
|
* Renders an Unlayer element tree to a plain text string.
|
|
853
881
|
*
|
|
854
|
-
*
|
|
882
|
+
* Renders the body markup then converts to plain text using
|
|
855
883
|
* `htmlToPlainText`. Useful for generating the text/plain MIME part
|
|
856
884
|
* of multipart emails (critical for deliverability).
|
|
857
885
|
*
|
|
@@ -876,19 +904,26 @@ declare function renderToPlainText(element: React__default.ReactElement, config?
|
|
|
876
904
|
interface HtmlParts {
|
|
877
905
|
/** `<head>` content: `<style>` blocks with component CSS, optional `<script>` tags */
|
|
878
906
|
head: string;
|
|
879
|
-
/**
|
|
907
|
+
/**
|
|
908
|
+
* The rendered body markup, wrapped in the renderer's host `<div>`. In
|
|
909
|
+
* email/document mode it contains the `<body>` tag itself; web mode has
|
|
910
|
+
* none. No doctype/html/head shell — embeddable as-is, or extract the
|
|
911
|
+
* `<body>` tag when composing a full document.
|
|
912
|
+
*/
|
|
880
913
|
body: string;
|
|
881
914
|
}
|
|
882
915
|
/**
|
|
883
916
|
* Renders an Unlayer element tree to separate head and body HTML strings.
|
|
884
917
|
*
|
|
885
|
-
*
|
|
886
|
-
*
|
|
887
|
-
* and
|
|
918
|
+
* Use this when your app owns the document shell — an existing page
|
|
919
|
+
* template, an ESP template with its own meta tags, an iframe srcdoc —
|
|
920
|
+
* and you want to place the `<style>` block and body markup yourself.
|
|
921
|
+
* For a complete ready-to-send document in one call, use
|
|
922
|
+
* {@link renderToHtml}.
|
|
888
923
|
*
|
|
889
924
|
* - `head` contains `<style>` tags with CSS generated by each component's
|
|
890
925
|
* head function (button hover colors, body fonts, link styles, etc.)
|
|
891
|
-
* - `body` is
|
|
926
|
+
* - `body` is the rendered body markup without any document shell
|
|
892
927
|
*
|
|
893
928
|
* @param element - A React element tree (e.g. `<Email><Row>...</Row></Email>`)
|
|
894
929
|
* @param config - Optional config overrides (mode, cdnBaseUrl, etc.)
|
|
@@ -972,4 +1007,104 @@ declare function renderToHtmlParts(element: React__default.ReactElement, config?
|
|
|
972
1007
|
declare function renderRowToJson(element: React__default.ReactElement): DesignRow;
|
|
973
1008
|
declare function renderToJson(element: React__default.ReactElement): DesignJSON;
|
|
974
1009
|
|
|
975
|
-
|
|
1010
|
+
/**
|
|
1011
|
+
* registerTool — render the editor's custom tools from code.
|
|
1012
|
+
*
|
|
1013
|
+
* Accepts the same tool definition object embedders already write for
|
|
1014
|
+
* `unlayer.registerTool` (see docs.unlayer.com › Custom Tools) and returns a
|
|
1015
|
+
* React component. One definition powers both runtimes:
|
|
1016
|
+
*
|
|
1017
|
+
* - The Builder uses `label`/`icon`/`options`/`renderer.Viewer`/`validator`
|
|
1018
|
+
* for its panel, canvas, and audit — Elements ignores those.
|
|
1019
|
+
* - Elements calls `renderer.exporters[mode](values)` to produce HTML and
|
|
1020
|
+
* collects `renderer.head` css/js like any built-in component, so code
|
|
1021
|
+
* output matches editor exports by construction — it is the same function.
|
|
1022
|
+
* - `renderToJson` emits `{ type: "custom", slug: <name>, values }`, the
|
|
1023
|
+
* shape the editor stores, so designs round-trip into the Builder where
|
|
1024
|
+
* the same tool is registered.
|
|
1025
|
+
*
|
|
1026
|
+
* Sanitization: like editor exports, the tool's HTML output is passed
|
|
1027
|
+
* through `toSafeHtml` when one is configured. The default config has NO
|
|
1028
|
+
* sanitizer — with untrusted values, configure `toSafeHtml` (same caveat
|
|
1029
|
+
* as the `<Html>` component).
|
|
1030
|
+
*/
|
|
1031
|
+
|
|
1032
|
+
/** Exporter: `(values) => html`. Extra args mirror built-in exporters and can be ignored. */
|
|
1033
|
+
type ToolExporter = (values: any, ...args: any[]) => string;
|
|
1034
|
+
/** One property in an options group — Elements reads only the default. */
|
|
1035
|
+
interface ToolOptionConfig {
|
|
1036
|
+
defaultValue?: unknown;
|
|
1037
|
+
/** Disabled options contribute no default */
|
|
1038
|
+
enabled?: boolean;
|
|
1039
|
+
[editorOnly: string]: unknown;
|
|
1040
|
+
}
|
|
1041
|
+
/** A property group: `options.<group>.options.<property>` */
|
|
1042
|
+
interface ToolOptionGroup {
|
|
1043
|
+
options?: Record<string, ToolOptionConfig | undefined>;
|
|
1044
|
+
[editorOnly: string]: unknown;
|
|
1045
|
+
}
|
|
1046
|
+
/**
|
|
1047
|
+
* The subset of the `unlayer.registerTool` config Elements reads. Extra
|
|
1048
|
+
* editor-only fields (label, icon, Viewer, validator, transformer, ...)
|
|
1049
|
+
* are accepted and ignored, so the same object can be passed to both APIs.
|
|
1050
|
+
*/
|
|
1051
|
+
interface ElementsToolConfig {
|
|
1052
|
+
/** Unique tool name — becomes the design JSON `slug` */
|
|
1053
|
+
name: string;
|
|
1054
|
+
/** Initial values for the tool's properties (win over option defaults) */
|
|
1055
|
+
values?: Record<string, any>;
|
|
1056
|
+
/**
|
|
1057
|
+
* Property groups. Real-world tools usually define their defaults here,
|
|
1058
|
+
* as each property's `defaultValue` — those seed the initial values,
|
|
1059
|
+
* with tool-level `values` taking precedence (the editor's order).
|
|
1060
|
+
*/
|
|
1061
|
+
options?: Record<string, ToolOptionGroup | undefined>;
|
|
1062
|
+
renderer: {
|
|
1063
|
+
/** Per-mode HTML exporters. `document` falls back to `web`. */
|
|
1064
|
+
exporters: Partial<Record<RenderMode, ToolExporter>>;
|
|
1065
|
+
/** Optional head contributions collected into the document `<head>` */
|
|
1066
|
+
head?: {
|
|
1067
|
+
css?: (values: any, ...args: any[]) => string | undefined;
|
|
1068
|
+
js?: (values: any, ...args: any[]) => string | undefined;
|
|
1069
|
+
tags?: (values: any, ...args: any[]) => string[] | undefined;
|
|
1070
|
+
};
|
|
1071
|
+
/** Editor-only canvas renderer — ignored by Elements */
|
|
1072
|
+
Viewer?: unknown;
|
|
1073
|
+
};
|
|
1074
|
+
/** React DevTools name (defaults to the tool name) */
|
|
1075
|
+
displayName?: string;
|
|
1076
|
+
/** Editor-only fields (label, icon, options, validator, ...) — ignored */
|
|
1077
|
+
[editorOnly: string]: unknown;
|
|
1078
|
+
}
|
|
1079
|
+
/** Props: the tool's values as flat props, plus a `values` escape hatch. */
|
|
1080
|
+
type ElementsToolProps = BaseItemComponentProps & Record<string, any> & {
|
|
1081
|
+
values?: Record<string, any>;
|
|
1082
|
+
};
|
|
1083
|
+
/**
|
|
1084
|
+
* Create a React component from a custom tool definition — a custom tool
|
|
1085
|
+
* is the custom component you create: the same term (and the same config)
|
|
1086
|
+
* as the editor's `unlayer.registerTool`, so one definition serves both.
|
|
1087
|
+
*
|
|
1088
|
+
* @example
|
|
1089
|
+
* ```tsx
|
|
1090
|
+
* const Countdown = registerTool({
|
|
1091
|
+
* name: "countdown",
|
|
1092
|
+
* values: { endTime: "", digitColor: "#404040" },
|
|
1093
|
+
* renderer: {
|
|
1094
|
+
* exporters: {
|
|
1095
|
+
* web: (values) => `<div style="color:${values.digitColor}">…</div>`,
|
|
1096
|
+
* email: (values) => `<table role="presentation">…</table>`,
|
|
1097
|
+
* },
|
|
1098
|
+
* },
|
|
1099
|
+
* });
|
|
1100
|
+
*
|
|
1101
|
+
* <Email><Row><Column>
|
|
1102
|
+
* <Countdown endTime="2026-08-01T00:00:00Z" digitColor="#e11d48" />
|
|
1103
|
+
* </Column></Row></Email>
|
|
1104
|
+
* ```
|
|
1105
|
+
*/
|
|
1106
|
+
declare function registerTool(tool: ElementsToolConfig): React__default.FC<ElementsToolProps>;
|
|
1107
|
+
/** Alias of {@link registerTool}. */
|
|
1108
|
+
declare const registerElementsTool: typeof registerTool;
|
|
1109
|
+
|
|
1110
|
+
export { Body, type BorderInput, Button, type ButtonProps, Column, type ColumnLayout, ColumnLayouts, DEFAULT_CONFIG, type DesignBody, type DesignColumn, type DesignContent, type DesignJSON, type DesignRow, Divider, type DividerProps, Document, type DocumentProps, type ElementsToolConfig, type ElementsToolProps, Email, type EmailProps, type FontFamilyInput, type FontWeightInput, Heading, type HeadingLevel, type HeadingProps, type Href, Html, type HtmlParts, type HtmlProps, type Icons, Image, type ImageProps, type ImageSrcInput, type LinkStyle, Menu, type MenuItem, type MenuProps, Page, type PageProps, Paragraph, type ParagraphProps, type RenderToHtmlOptions, Row, type RowProps, type SizeInput, Social, type SocialIcon, type SocialProps, Table, type TableProps, type TextAlign, type TextStyleProps, type ToolExporter, type UnlayerConfig, UnlayerProvider, type UnlayerProviderProps, type ValidColumnLayout, Video, type VideoProps, type VideoSource, htmlToTextJson, registerElementsTool, registerTool, renderRowToJson, renderToHtml, renderToHtmlParts, renderToJson, renderToPlainText, useUnlayerConfig, validateColumnLayout };
|
package/dist/index.d.ts
CHANGED
|
@@ -118,6 +118,8 @@ interface MenuItem {
|
|
|
118
118
|
type RenderMode = "web" | "email" | "document";
|
|
119
119
|
interface DesignContent {
|
|
120
120
|
type: string;
|
|
121
|
+
/** Custom tool name — present when `type` is "custom" */
|
|
122
|
+
slug?: string;
|
|
121
123
|
values: Record<string, any>;
|
|
122
124
|
}
|
|
123
125
|
interface DesignColumn {
|
|
@@ -312,6 +314,10 @@ interface BaseItemComponentProps {
|
|
|
312
314
|
* string ("10px", "16px 24px"). Applied by the containing Column. */
|
|
313
315
|
containerPadding?: SizeInput;
|
|
314
316
|
index?: number;
|
|
317
|
+
/** @internal — content id allocated by the containing Column; keeps the
|
|
318
|
+
* value-level _meta.htmlID unique per instance and aligned with the
|
|
319
|
+
* wrapper id and head/json numbering. */
|
|
320
|
+
_metaHtmlId?: string;
|
|
315
321
|
colIndex?: number;
|
|
316
322
|
cells?: any[];
|
|
317
323
|
bodyValues?: any;
|
|
@@ -826,32 +832,54 @@ declare const UnlayerProvider: React__default.FC<UnlayerProviderProps>;
|
|
|
826
832
|
declare function useUnlayerConfig(): UnlayerConfig;
|
|
827
833
|
|
|
828
834
|
/**
|
|
829
|
-
*
|
|
835
|
+
* Options for renderToHtml — config overrides plus document-level extras.
|
|
836
|
+
*/
|
|
837
|
+
interface RenderToHtmlOptions extends Partial<UnlayerConfig> {
|
|
838
|
+
/** Document `<title>` */
|
|
839
|
+
title?: string;
|
|
840
|
+
/**
|
|
841
|
+
* Web-font stylesheets to load via `<link rel="stylesheet">` tags.
|
|
842
|
+
* Elements has no font registry, so pass the URLs for any non-system
|
|
843
|
+
* fonts your design uses (e.g. Google Fonts CSS URLs).
|
|
844
|
+
*/
|
|
845
|
+
fonts?: Array<{
|
|
846
|
+
url: string;
|
|
847
|
+
}>;
|
|
848
|
+
}
|
|
849
|
+
/**
|
|
850
|
+
* Renders an Unlayer element tree to a complete HTML document — from
|
|
851
|
+
* `<!DOCTYPE ...>` to `</html>` — matching the editor's exportHtml layouts.
|
|
830
852
|
*
|
|
831
|
-
* -
|
|
832
|
-
* -
|
|
833
|
-
*
|
|
853
|
+
* Per-mode document shells (mirroring the editor's layout templates):
|
|
854
|
+
* - `email`: XHTML transitional doctype, VML/Office namespaces, and the MSO
|
|
855
|
+
* conditional comments Outlook needs
|
|
856
|
+
* - `web`: HTML5 doctype with standard viewport/charset meta tags
|
|
857
|
+
* - `document`: XHTML transitional doctype for print/PDF pipelines
|
|
834
858
|
*
|
|
835
|
-
* @
|
|
836
|
-
*
|
|
837
|
-
*
|
|
859
|
+
* Use {@link renderToHtmlParts} instead when your app owns the document
|
|
860
|
+
* shell and only needs the head/body chunks.
|
|
861
|
+
*
|
|
862
|
+
* @param element - A React element tree (e.g. `<Email><Row>...</Row></Email>`)
|
|
863
|
+
* @param options - Config overrides (mode, cdnBaseUrl, etc.) plus `title` and `fonts`
|
|
864
|
+
* @returns Complete HTML document string
|
|
838
865
|
* @throws {Error} If rendering fails, with a helpful message
|
|
839
866
|
*
|
|
840
867
|
* @example
|
|
841
868
|
* ```tsx
|
|
842
|
-
* import { renderToHtml,
|
|
869
|
+
* import { renderToHtml, Email, Row, Column, Paragraph } from "@unlayer/react-elements";
|
|
843
870
|
*
|
|
844
871
|
* const html = renderToHtml(
|
|
845
|
-
* <
|
|
846
|
-
* {
|
|
872
|
+
* <Email><Row><Column><Paragraph>Hello</Paragraph></Column></Row></Email>,
|
|
873
|
+
* { title: "Welcome" }
|
|
847
874
|
* );
|
|
875
|
+
* // "<!DOCTYPE HTML PUBLIC ...><html ...>...</html>"
|
|
848
876
|
* ```
|
|
849
877
|
*/
|
|
850
|
-
declare function renderToHtml(element: React__default.ReactElement,
|
|
878
|
+
declare function renderToHtml(element: React__default.ReactElement, options?: RenderToHtmlOptions): string;
|
|
851
879
|
/**
|
|
852
880
|
* Renders an Unlayer element tree to a plain text string.
|
|
853
881
|
*
|
|
854
|
-
*
|
|
882
|
+
* Renders the body markup then converts to plain text using
|
|
855
883
|
* `htmlToPlainText`. Useful for generating the text/plain MIME part
|
|
856
884
|
* of multipart emails (critical for deliverability).
|
|
857
885
|
*
|
|
@@ -876,19 +904,26 @@ declare function renderToPlainText(element: React__default.ReactElement, config?
|
|
|
876
904
|
interface HtmlParts {
|
|
877
905
|
/** `<head>` content: `<style>` blocks with component CSS, optional `<script>` tags */
|
|
878
906
|
head: string;
|
|
879
|
-
/**
|
|
907
|
+
/**
|
|
908
|
+
* The rendered body markup, wrapped in the renderer's host `<div>`. In
|
|
909
|
+
* email/document mode it contains the `<body>` tag itself; web mode has
|
|
910
|
+
* none. No doctype/html/head shell — embeddable as-is, or extract the
|
|
911
|
+
* `<body>` tag when composing a full document.
|
|
912
|
+
*/
|
|
880
913
|
body: string;
|
|
881
914
|
}
|
|
882
915
|
/**
|
|
883
916
|
* Renders an Unlayer element tree to separate head and body HTML strings.
|
|
884
917
|
*
|
|
885
|
-
*
|
|
886
|
-
*
|
|
887
|
-
* and
|
|
918
|
+
* Use this when your app owns the document shell — an existing page
|
|
919
|
+
* template, an ESP template with its own meta tags, an iframe srcdoc —
|
|
920
|
+
* and you want to place the `<style>` block and body markup yourself.
|
|
921
|
+
* For a complete ready-to-send document in one call, use
|
|
922
|
+
* {@link renderToHtml}.
|
|
888
923
|
*
|
|
889
924
|
* - `head` contains `<style>` tags with CSS generated by each component's
|
|
890
925
|
* head function (button hover colors, body fonts, link styles, etc.)
|
|
891
|
-
* - `body` is
|
|
926
|
+
* - `body` is the rendered body markup without any document shell
|
|
892
927
|
*
|
|
893
928
|
* @param element - A React element tree (e.g. `<Email><Row>...</Row></Email>`)
|
|
894
929
|
* @param config - Optional config overrides (mode, cdnBaseUrl, etc.)
|
|
@@ -972,4 +1007,104 @@ declare function renderToHtmlParts(element: React__default.ReactElement, config?
|
|
|
972
1007
|
declare function renderRowToJson(element: React__default.ReactElement): DesignRow;
|
|
973
1008
|
declare function renderToJson(element: React__default.ReactElement): DesignJSON;
|
|
974
1009
|
|
|
975
|
-
|
|
1010
|
+
/**
|
|
1011
|
+
* registerTool — render the editor's custom tools from code.
|
|
1012
|
+
*
|
|
1013
|
+
* Accepts the same tool definition object embedders already write for
|
|
1014
|
+
* `unlayer.registerTool` (see docs.unlayer.com › Custom Tools) and returns a
|
|
1015
|
+
* React component. One definition powers both runtimes:
|
|
1016
|
+
*
|
|
1017
|
+
* - The Builder uses `label`/`icon`/`options`/`renderer.Viewer`/`validator`
|
|
1018
|
+
* for its panel, canvas, and audit — Elements ignores those.
|
|
1019
|
+
* - Elements calls `renderer.exporters[mode](values)` to produce HTML and
|
|
1020
|
+
* collects `renderer.head` css/js like any built-in component, so code
|
|
1021
|
+
* output matches editor exports by construction — it is the same function.
|
|
1022
|
+
* - `renderToJson` emits `{ type: "custom", slug: <name>, values }`, the
|
|
1023
|
+
* shape the editor stores, so designs round-trip into the Builder where
|
|
1024
|
+
* the same tool is registered.
|
|
1025
|
+
*
|
|
1026
|
+
* Sanitization: like editor exports, the tool's HTML output is passed
|
|
1027
|
+
* through `toSafeHtml` when one is configured. The default config has NO
|
|
1028
|
+
* sanitizer — with untrusted values, configure `toSafeHtml` (same caveat
|
|
1029
|
+
* as the `<Html>` component).
|
|
1030
|
+
*/
|
|
1031
|
+
|
|
1032
|
+
/** Exporter: `(values) => html`. Extra args mirror built-in exporters and can be ignored. */
|
|
1033
|
+
type ToolExporter = (values: any, ...args: any[]) => string;
|
|
1034
|
+
/** One property in an options group — Elements reads only the default. */
|
|
1035
|
+
interface ToolOptionConfig {
|
|
1036
|
+
defaultValue?: unknown;
|
|
1037
|
+
/** Disabled options contribute no default */
|
|
1038
|
+
enabled?: boolean;
|
|
1039
|
+
[editorOnly: string]: unknown;
|
|
1040
|
+
}
|
|
1041
|
+
/** A property group: `options.<group>.options.<property>` */
|
|
1042
|
+
interface ToolOptionGroup {
|
|
1043
|
+
options?: Record<string, ToolOptionConfig | undefined>;
|
|
1044
|
+
[editorOnly: string]: unknown;
|
|
1045
|
+
}
|
|
1046
|
+
/**
|
|
1047
|
+
* The subset of the `unlayer.registerTool` config Elements reads. Extra
|
|
1048
|
+
* editor-only fields (label, icon, Viewer, validator, transformer, ...)
|
|
1049
|
+
* are accepted and ignored, so the same object can be passed to both APIs.
|
|
1050
|
+
*/
|
|
1051
|
+
interface ElementsToolConfig {
|
|
1052
|
+
/** Unique tool name — becomes the design JSON `slug` */
|
|
1053
|
+
name: string;
|
|
1054
|
+
/** Initial values for the tool's properties (win over option defaults) */
|
|
1055
|
+
values?: Record<string, any>;
|
|
1056
|
+
/**
|
|
1057
|
+
* Property groups. Real-world tools usually define their defaults here,
|
|
1058
|
+
* as each property's `defaultValue` — those seed the initial values,
|
|
1059
|
+
* with tool-level `values` taking precedence (the editor's order).
|
|
1060
|
+
*/
|
|
1061
|
+
options?: Record<string, ToolOptionGroup | undefined>;
|
|
1062
|
+
renderer: {
|
|
1063
|
+
/** Per-mode HTML exporters. `document` falls back to `web`. */
|
|
1064
|
+
exporters: Partial<Record<RenderMode, ToolExporter>>;
|
|
1065
|
+
/** Optional head contributions collected into the document `<head>` */
|
|
1066
|
+
head?: {
|
|
1067
|
+
css?: (values: any, ...args: any[]) => string | undefined;
|
|
1068
|
+
js?: (values: any, ...args: any[]) => string | undefined;
|
|
1069
|
+
tags?: (values: any, ...args: any[]) => string[] | undefined;
|
|
1070
|
+
};
|
|
1071
|
+
/** Editor-only canvas renderer — ignored by Elements */
|
|
1072
|
+
Viewer?: unknown;
|
|
1073
|
+
};
|
|
1074
|
+
/** React DevTools name (defaults to the tool name) */
|
|
1075
|
+
displayName?: string;
|
|
1076
|
+
/** Editor-only fields (label, icon, options, validator, ...) — ignored */
|
|
1077
|
+
[editorOnly: string]: unknown;
|
|
1078
|
+
}
|
|
1079
|
+
/** Props: the tool's values as flat props, plus a `values` escape hatch. */
|
|
1080
|
+
type ElementsToolProps = BaseItemComponentProps & Record<string, any> & {
|
|
1081
|
+
values?: Record<string, any>;
|
|
1082
|
+
};
|
|
1083
|
+
/**
|
|
1084
|
+
* Create a React component from a custom tool definition — a custom tool
|
|
1085
|
+
* is the custom component you create: the same term (and the same config)
|
|
1086
|
+
* as the editor's `unlayer.registerTool`, so one definition serves both.
|
|
1087
|
+
*
|
|
1088
|
+
* @example
|
|
1089
|
+
* ```tsx
|
|
1090
|
+
* const Countdown = registerTool({
|
|
1091
|
+
* name: "countdown",
|
|
1092
|
+
* values: { endTime: "", digitColor: "#404040" },
|
|
1093
|
+
* renderer: {
|
|
1094
|
+
* exporters: {
|
|
1095
|
+
* web: (values) => `<div style="color:${values.digitColor}">…</div>`,
|
|
1096
|
+
* email: (values) => `<table role="presentation">…</table>`,
|
|
1097
|
+
* },
|
|
1098
|
+
* },
|
|
1099
|
+
* });
|
|
1100
|
+
*
|
|
1101
|
+
* <Email><Row><Column>
|
|
1102
|
+
* <Countdown endTime="2026-08-01T00:00:00Z" digitColor="#e11d48" />
|
|
1103
|
+
* </Column></Row></Email>
|
|
1104
|
+
* ```
|
|
1105
|
+
*/
|
|
1106
|
+
declare function registerTool(tool: ElementsToolConfig): React__default.FC<ElementsToolProps>;
|
|
1107
|
+
/** Alias of {@link registerTool}. */
|
|
1108
|
+
declare const registerElementsTool: typeof registerTool;
|
|
1109
|
+
|
|
1110
|
+
export { Body, type BorderInput, Button, type ButtonProps, Column, type ColumnLayout, ColumnLayouts, DEFAULT_CONFIG, type DesignBody, type DesignColumn, type DesignContent, type DesignJSON, type DesignRow, Divider, type DividerProps, Document, type DocumentProps, type ElementsToolConfig, type ElementsToolProps, Email, type EmailProps, type FontFamilyInput, type FontWeightInput, Heading, type HeadingLevel, type HeadingProps, type Href, Html, type HtmlParts, type HtmlProps, type Icons, Image, type ImageProps, type ImageSrcInput, type LinkStyle, Menu, type MenuItem, type MenuProps, Page, type PageProps, Paragraph, type ParagraphProps, type RenderToHtmlOptions, Row, type RowProps, type SizeInput, Social, type SocialIcon, type SocialProps, Table, type TableProps, type TextAlign, type TextStyleProps, type ToolExporter, type UnlayerConfig, UnlayerProvider, type UnlayerProviderProps, type ValidColumnLayout, Video, type VideoProps, type VideoSource, htmlToTextJson, registerElementsTool, registerTool, renderRowToJson, renderToHtml, renderToHtmlParts, renderToJson, renderToPlainText, useUnlayerConfig, validateColumnLayout };
|