@unlayer/react-elements 0.1.17 → 0.1.19

package/dist/index.d.cts

@@ -118,6 +118,8 @@ interface MenuItem {
 type RenderMode = "web" | "email" | "document";
 interface DesignContent {
     type: string;
+    /** Custom tool name — present when `type` is "custom" */
+    slug?: string;
     values: Record<string, any>;
 }
 interface DesignColumn {
@@ -312,6 +314,10 @@ interface BaseItemComponentProps {
      *  string ("10px", "16px 24px"). Applied by the containing Column. */
     containerPadding?: SizeInput;
     index?: number;
+    /** @internal — content id allocated by the containing Column; keeps the
+     *  value-level _meta.htmlID unique per instance and aligned with the
+     *  wrapper id and head/json numbering. */
+    _metaHtmlId?: string;
     colIndex?: number;
     cells?: any[];
     bodyValues?: any;
@@ -896,7 +902,11 @@ declare function renderToPlainText(element: React__default.ReactElement, config?
  * Result of renderToHtmlParts — head and body as separate strings.
  */
 interface HtmlParts {
-    /** `<head>` content: `<style>` blocks with component CSS, optional `<script>` tags */
+    /**
+     * Pre-assembled `<head>` content: the css in a `<style>` tag, the js in a
+     * `<script>` tag, and the tags — joined and ready to drop into a document.
+     * Equivalent to composing the granular fields below yourself.
+     */
     head: string;
     /**
      * The rendered body markup, wrapped in the renderer's host `<div>`. In
@@ -905,6 +915,21 @@ interface HtmlParts {
      * `<body>` tag when composing a full document.
      */
     body: string;
+    /** Raw component CSS (no `<style>` wrapper) — e.g. for inlining pipelines */
+    css: string;
+    /** Raw component JS (no `<script>` wrapper); empty for most email designs */
+    js: string;
+    /**
+     * Individual head tags (`<meta>`, `<link>`, ...) contributed by components.
+     * Not part of the editor's documented chunk parameters, but exposed here
+     * because `head` can contain them — without this field, reassembling the
+     * head from `css` + `js` would silently drop them. Usually empty.
+     *
+     * There is deliberately no `fonts` chunk: Elements has no font registry to
+     * resolve font URLs from — pass stylesheet URLs via renderToHtml's `fonts`
+     * option instead.
+     */
+    tags: string[];
 }
 /**
  * Renders an Unlayer element tree to separate head and body HTML strings.
@@ -1001,4 +1026,104 @@ declare function renderToHtmlParts(element: React__default.ReactElement, config?
 declare function renderRowToJson(element: React__default.ReactElement): DesignRow;
 declare function renderToJson(element: React__default.ReactElement): DesignJSON;
 
-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, 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 UnlayerConfig, UnlayerProvider, type UnlayerProviderProps, type ValidColumnLayout, Video, type VideoProps, type VideoSource, htmlToTextJson, renderRowToJson, renderToHtml, renderToHtmlParts, renderToJson, renderToPlainText, useUnlayerConfig, validateColumnLayout };
+/**
+ * registerTool — render the editor's custom tools from code.
+ *
+ * Accepts the same tool definition object embedders already write for
+ * `unlayer.registerTool` (see docs.unlayer.com › Custom Tools) and returns a
+ * React component. One definition powers both runtimes:
+ *
+ * - The Builder uses `label`/`icon`/`options`/`renderer.Viewer`/`validator`
+ *   for its panel, canvas, and audit — Elements ignores those.
+ * - Elements calls `renderer.exporters[mode](values)` to produce HTML and
+ *   collects `renderer.head` css/js like any built-in component, so code
+ *   output matches editor exports by construction — it is the same function.
+ * - `renderToJson` emits `{ type: "custom", slug: <name>, values }`, the
+ *   shape the editor stores, so designs round-trip into the Builder where
+ *   the same tool is registered.
+ *
+ * Sanitization: like editor exports, the tool's HTML output is passed
+ * through `toSafeHtml` when one is configured. The default config has NO
+ * sanitizer — with untrusted values, configure `toSafeHtml` (same caveat
+ * as the `<Html>` component).
+ */
+
+/** Exporter: `(values) => html`. Extra args mirror built-in exporters and can be ignored. */
+type ToolExporter = (values: any, ...args: any[]) => string;
+/** One property in an options group — Elements reads only the default. */
+interface ToolOptionConfig {
+    defaultValue?: unknown;
+    /** Disabled options contribute no default */
+    enabled?: boolean;
+    [editorOnly: string]: unknown;
+}
+/** A property group: `options.<group>.options.<property>` */
+interface ToolOptionGroup {
+    options?: Record<string, ToolOptionConfig | undefined>;
+    [editorOnly: string]: unknown;
+}
+/**
+ * The subset of the `unlayer.registerTool` config Elements reads. Extra
+ * editor-only fields (label, icon, Viewer, validator, transformer, ...)
+ * are accepted and ignored, so the same object can be passed to both APIs.
+ */
+interface ElementsToolConfig {
+    /** Unique tool name — becomes the design JSON `slug` */
+    name: string;
+    /** Initial values for the tool's properties (win over option defaults) */
+    values?: Record<string, any>;
+    /**
+     * Property groups. Real-world tools usually define their defaults here,
+     * as each property's `defaultValue` — those seed the initial values,
+     * with tool-level `values` taking precedence (the editor's order).
+     */
+    options?: Record<string, ToolOptionGroup | undefined>;
+    renderer: {
+        /** Per-mode HTML exporters. `document` falls back to `web`. */
+        exporters: Partial<Record<RenderMode, ToolExporter>>;
+        /** Optional head contributions collected into the document `<head>` */
+        head?: {
+            css?: (values: any, ...args: any[]) => string | undefined;
+            js?: (values: any, ...args: any[]) => string | undefined;
+            tags?: (values: any, ...args: any[]) => string[] | undefined;
+        };
+        /** Editor-only canvas renderer — ignored by Elements */
+        Viewer?: unknown;
+    };
+    /** React DevTools name (defaults to the tool name) */
+    displayName?: string;
+    /** Editor-only fields (label, icon, options, validator, ...) — ignored */
+    [editorOnly: string]: unknown;
+}
+/** Props: the tool's values as flat props, plus a `values` escape hatch. */
+type ElementsToolProps = BaseItemComponentProps & Record<string, any> & {
+    values?: Record<string, any>;
+};
+/**
+ * Create a React component from a custom tool definition — a custom tool
+ * is the custom component you create: the same term (and the same config)
+ * as the editor's `unlayer.registerTool`, so one definition serves both.
+ *
+ * @example
+ * ```tsx
+ * const Countdown = registerTool({
+ *   name: "countdown",
+ *   values: { endTime: "", digitColor: "#404040" },
+ *   renderer: {
+ *     exporters: {
+ *       web:   (values) => `<div style="color:${values.digitColor}">…</div>`,
+ *       email: (values) => `<table role="presentation">…</table>`,
+ *     },
+ *   },
+ * });
+ *
+ * <Email><Row><Column>
+ *   <Countdown endTime="2026-08-01T00:00:00Z" digitColor="#e11d48" />
+ * </Column></Row></Email>
+ * ```
+ */
+declare function registerTool(tool: ElementsToolConfig): React__default.FC<ElementsToolProps>;
+/** Alias of {@link registerTool}. */
+declare const registerElementsTool: typeof registerTool;
+
+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

@@ -118,6 +118,8 @@ interface MenuItem {
 type RenderMode = "web" | "email" | "document";
 interface DesignContent {
     type: string;
+    /** Custom tool name — present when `type` is "custom" */
+    slug?: string;
     values: Record<string, any>;
 }
 interface DesignColumn {
@@ -312,6 +314,10 @@ interface BaseItemComponentProps {
      *  string ("10px", "16px 24px"). Applied by the containing Column. */
     containerPadding?: SizeInput;
     index?: number;
+    /** @internal — content id allocated by the containing Column; keeps the
+     *  value-level _meta.htmlID unique per instance and aligned with the
+     *  wrapper id and head/json numbering. */
+    _metaHtmlId?: string;
     colIndex?: number;
     cells?: any[];
     bodyValues?: any;
@@ -896,7 +902,11 @@ declare function renderToPlainText(element: React__default.ReactElement, config?
  * Result of renderToHtmlParts — head and body as separate strings.
  */
 interface HtmlParts {
-    /** `<head>` content: `<style>` blocks with component CSS, optional `<script>` tags */
+    /**
+     * Pre-assembled `<head>` content: the css in a `<style>` tag, the js in a
+     * `<script>` tag, and the tags — joined and ready to drop into a document.
+     * Equivalent to composing the granular fields below yourself.
+     */
     head: string;
     /**
      * The rendered body markup, wrapped in the renderer's host `<div>`. In
@@ -905,6 +915,21 @@ interface HtmlParts {
      * `<body>` tag when composing a full document.
      */
     body: string;
+    /** Raw component CSS (no `<style>` wrapper) — e.g. for inlining pipelines */
+    css: string;
+    /** Raw component JS (no `<script>` wrapper); empty for most email designs */
+    js: string;
+    /**
+     * Individual head tags (`<meta>`, `<link>`, ...) contributed by components.
+     * Not part of the editor's documented chunk parameters, but exposed here
+     * because `head` can contain them — without this field, reassembling the
+     * head from `css` + `js` would silently drop them. Usually empty.
+     *
+     * There is deliberately no `fonts` chunk: Elements has no font registry to
+     * resolve font URLs from — pass stylesheet URLs via renderToHtml's `fonts`
+     * option instead.
+     */
+    tags: string[];
 }
 /**
  * Renders an Unlayer element tree to separate head and body HTML strings.
@@ -1001,4 +1026,104 @@ declare function renderToHtmlParts(element: React__default.ReactElement, config?
 declare function renderRowToJson(element: React__default.ReactElement): DesignRow;
 declare function renderToJson(element: React__default.ReactElement): DesignJSON;
 
-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, 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 UnlayerConfig, UnlayerProvider, type UnlayerProviderProps, type ValidColumnLayout, Video, type VideoProps, type VideoSource, htmlToTextJson, renderRowToJson, renderToHtml, renderToHtmlParts, renderToJson, renderToPlainText, useUnlayerConfig, validateColumnLayout };
+/**
+ * registerTool — render the editor's custom tools from code.
+ *
+ * Accepts the same tool definition object embedders already write for
+ * `unlayer.registerTool` (see docs.unlayer.com › Custom Tools) and returns a
+ * React component. One definition powers both runtimes:
+ *
+ * - The Builder uses `label`/`icon`/`options`/`renderer.Viewer`/`validator`
+ *   for its panel, canvas, and audit — Elements ignores those.
+ * - Elements calls `renderer.exporters[mode](values)` to produce HTML and
+ *   collects `renderer.head` css/js like any built-in component, so code
+ *   output matches editor exports by construction — it is the same function.
+ * - `renderToJson` emits `{ type: "custom", slug: <name>, values }`, the
+ *   shape the editor stores, so designs round-trip into the Builder where
+ *   the same tool is registered.
+ *
+ * Sanitization: like editor exports, the tool's HTML output is passed
+ * through `toSafeHtml` when one is configured. The default config has NO
+ * sanitizer — with untrusted values, configure `toSafeHtml` (same caveat
+ * as the `<Html>` component).
+ */
+
+/** Exporter: `(values) => html`. Extra args mirror built-in exporters and can be ignored. */
+type ToolExporter = (values: any, ...args: any[]) => string;
+/** One property in an options group — Elements reads only the default. */
+interface ToolOptionConfig {
+    defaultValue?: unknown;
+    /** Disabled options contribute no default */
+    enabled?: boolean;
+    [editorOnly: string]: unknown;
+}
+/** A property group: `options.<group>.options.<property>` */
+interface ToolOptionGroup {
+    options?: Record<string, ToolOptionConfig | undefined>;
+    [editorOnly: string]: unknown;
+}
+/**
+ * The subset of the `unlayer.registerTool` config Elements reads. Extra
+ * editor-only fields (label, icon, Viewer, validator, transformer, ...)
+ * are accepted and ignored, so the same object can be passed to both APIs.
+ */
+interface ElementsToolConfig {
+    /** Unique tool name — becomes the design JSON `slug` */
+    name: string;
+    /** Initial values for the tool's properties (win over option defaults) */
+    values?: Record<string, any>;
+    /**
+     * Property groups. Real-world tools usually define their defaults here,
+     * as each property's `defaultValue` — those seed the initial values,
+     * with tool-level `values` taking precedence (the editor's order).
+     */
+    options?: Record<string, ToolOptionGroup | undefined>;
+    renderer: {
+        /** Per-mode HTML exporters. `document` falls back to `web`. */
+        exporters: Partial<Record<RenderMode, ToolExporter>>;
+        /** Optional head contributions collected into the document `<head>` */
+        head?: {
+            css?: (values: any, ...args: any[]) => string | undefined;
+            js?: (values: any, ...args: any[]) => string | undefined;
+            tags?: (values: any, ...args: any[]) => string[] | undefined;
+        };
+        /** Editor-only canvas renderer — ignored by Elements */
+        Viewer?: unknown;
+    };
+    /** React DevTools name (defaults to the tool name) */
+    displayName?: string;
+    /** Editor-only fields (label, icon, options, validator, ...) — ignored */
+    [editorOnly: string]: unknown;
+}
+/** Props: the tool's values as flat props, plus a `values` escape hatch. */
+type ElementsToolProps = BaseItemComponentProps & Record<string, any> & {
+    values?: Record<string, any>;
+};
+/**
+ * Create a React component from a custom tool definition — a custom tool
+ * is the custom component you create: the same term (and the same config)
+ * as the editor's `unlayer.registerTool`, so one definition serves both.
+ *
+ * @example
+ * ```tsx
+ * const Countdown = registerTool({
+ *   name: "countdown",
+ *   values: { endTime: "", digitColor: "#404040" },
+ *   renderer: {
+ *     exporters: {
+ *       web:   (values) => `<div style="color:${values.digitColor}">…</div>`,
+ *       email: (values) => `<table role="presentation">…</table>`,
+ *     },
+ *   },
+ * });
+ *
+ * <Email><Row><Column>
+ *   <Countdown endTime="2026-08-01T00:00:00Z" digitColor="#e11d48" />
+ * </Column></Row></Email>
+ * ```
+ */
+declare function registerTool(tool: ElementsToolConfig): React__default.FC<ElementsToolProps>;
+/** Alias of {@link registerTool}. */
+declare const registerElementsTool: typeof registerTool;
+
+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.js

@@ -613,16 +613,6 @@ function nextHtmlId(config, prefix) {
   ids[prefix] = (ids[prefix] || 0) + 1;
   return `${prefix}_${ids[prefix]}`;
 }
-function ensureMeta(values, type, index = 0) {
-  return {
-    ...values,
-    _meta: {
-      htmlID: `u_content_${type.toLowerCase()}_${index + 1}`,
-      htmlClassNames: `u_content_${type.toLowerCase()}`,
-      ...values._meta || {}
-    }
-  };
-}
 function renderComponent(config) {
   const { type, values, className, style, args = [], innerHTML, _config, exporter, metaContext } = config;
   try {
@@ -675,6 +665,7 @@ function createItemComponent(config) {
       style,
       // Internal props
       index = 0,
+      _metaHtmlId,
       colIndex = 0,
       cells = [],
       bodyValues = {},
@@ -692,11 +683,15 @@ function createItemComponent(config) {
       ...restProps
     });
     const finalValues = mergeValues(config.defaultValues, mappedValues);
-    const valuesWithMeta = ensureMeta(
-      finalValues,
-      config.name.toLowerCase(),
-      index
-    );
+    const metaName = config.metaName ?? config.name.toLowerCase();
+    const valuesWithMeta = {
+      ...finalValues,
+      _meta: {
+        htmlID: _metaHtmlId ?? `u_content_${metaName}_${index + 1}`,
+        htmlClassNames: `u_content_${metaName}`,
+        ...finalValues._meta || {}
+      }
+    };
     const safeBodyValues = {
       contentWidth: "500px",
       ...bodyValues
@@ -745,7 +740,11 @@ function createItemComponent(config) {
   ItemComponent[UNLAYER_CONFIG_KEY] = {
     name: config.name,
     defaultValues: config.defaultValues,
-    propMapper: config.propMapper
+    propMapper: config.propMapper,
+    contentType: config.contentType,
+    slug: config.slug,
+    metaName: config.metaName,
+    head: config.head
   };
   return ItemComponent;
 }
@@ -1367,9 +1366,12 @@ var Column = (props) => {
           if (typeof child.type === "function") {
             const ComponentType = child.type;
             const renderFn = ComponentType[UNLAYER_RENDER_KEY] || ComponentType;
+            const componentName = ComponentType?.[UNLAYER_CONFIG_KEY]?.metaName ?? (ComponentType?.displayName || ComponentType?.name || "component").toLowerCase();
+            const contentHtmlId = nextHtmlId(_config, `u_content_${componentName}`);
             const rendered = renderFn({
               ...child.props,
               _config,
+              _metaHtmlId: contentHtmlId,
               colIndex: index,
               cells,
               bodyValues,
@@ -1378,15 +1380,13 @@ var Column = (props) => {
             });
             if (rendered && typeof rendered === "object" && rendered.props && rendered.props.dangerouslySetInnerHTML) {
               const componentHTML = rendered.props.dangerouslySetInnerHTML.__html;
-              const componentType = child.type;
-              const componentName = (componentType?.displayName || componentType?.name || "component").toLowerCase();
               const childProps = child.props;
               const rawContainerPadding = childProps.containerPadding ?? childProps.values?.containerPadding ?? DEFAULT_CONTAINER_PADDING2;
               const containerPadding = typeof rawContainerPadding === "number" ? `${rawContainerPadding}px` : rawContainerPadding;
               const contentValues = {
                 containerPadding,
                 _meta: {
-                  htmlID: nextHtmlId(_config, `u_content_${componentName}`),
+                  htmlID: contentHtmlId,
                   htmlClassNames: `u_content_${componentName}`
                 }
               };
@@ -1557,7 +1557,7 @@ UnlayerProvider.displayName = "UnlayerProvider";
 function useUnlayerConfig() {
   return useContext(getUnlayerContext());
 }
-function ensureMeta2(values, type, index = 0) {
+function ensureMeta(values, type, index = 0) {
   return {
     ...values,
     _meta: {
@@ -1638,17 +1638,17 @@ function walkItem(element, bodyValues, displayMode, headConfig, counters, styles
   const { children, ...restProps } = element.props;
   const mappedValues = propMapper({ children, ...restProps });
   const finalValues = mergeValues(defaultValues, mappedValues);
-  const contentType = name.toLowerCase();
+  const contentType = config.metaName ?? name.toLowerCase();
   const count = nextCounter(counters, `u_content_${contentType}`);
-  const valuesWithMeta = ensureMeta2(finalValues, contentType, count - 1);
-  const head = heads[name];
+  const valuesWithMeta = ensureMeta(finalValues, contentType, count - 1);
+  const head = config.head ?? heads[name];
   callHead(head, valuesWithMeta, bodyValues, displayMode, headConfig, styles, scripts, tags);
 }
 function walkColumn(element, bodyValues, rowValues, displayMode, headConfig, counters, styles, scripts, tags) {
   const semanticProps = extractSemanticProps(element.props);
   const mapped = mapSemanticProps(semanticProps, COLUMN_DEFAULTS, "Column");
   const count = nextCounter(counters, "u_column");
-  const columnValues = ensureMeta2(mergeValues(COLUMN_DEFAULTS, mapped), "column", count - 1);
+  const columnValues = ensureMeta(mergeValues(COLUMN_DEFAULTS, mapped), "column", count - 1);
   const columnHead = heads["Column"];
   callHead(columnHead, columnValues, bodyValues, displayMode, headConfig, styles, scripts, tags);
   const children = collectChildren(element.props.children);
@@ -1660,7 +1660,7 @@ function walkRow(element, bodyValues, displayMode, headConfig, counters, styles,
   const semanticProps = extractSemanticProps(element.props, ["layout"]);
   const mapped = mapSemanticProps(semanticProps, ROW_DEFAULTS, "Row");
   const count = nextCounter(counters, "u_row");
-  const rowValues = ensureMeta2(mergeValues(ROW_DEFAULTS, mapped), "row", count - 1);
+  const rowValues = ensureMeta(mergeValues(ROW_DEFAULTS, mapped), "row", count - 1);
   const rowHead = heads["Row"];
   callHead(rowHead, rowValues, bodyValues, displayMode, headConfig, styles, scripts, tags);
   const children = collectChildren(element.props.children);
@@ -1683,7 +1683,7 @@ function extractHeadFromTree(element, options) {
   const counters = {};
   const semanticProps = extractSemanticProps(element.props);
   const mapped = mapSemanticProps(semanticProps, BODY_DEFAULTS, "Body");
-  const bodyValues = ensureMeta2(mergeValues(BODY_DEFAULTS, mapped), "body", 0);
+  const bodyValues = ensureMeta(mergeValues(BODY_DEFAULTS, mapped), "body", 0);
   const bodyHead = heads["Body"];
   callHead(bodyHead, bodyValues, bodyValues, displayMode, headConfig, styles, scripts, tags);
   const children = collectChildren(element.props.children);
@@ -1850,7 +1850,10 @@ function renderToHtmlParts(element, config) {
   }
   return {
     head: headParts.join("\n"),
-    body
+    body,
+    css,
+    js,
+    tags
   };
 }
 var schemaVersion = schemaVersion$1 ?? 24;
@@ -1956,10 +1959,11 @@ function processItem(element, counters, layout = {}) {
       `[Unlayer] renderToJson: <${name2}> is not a recognized Unlayer item component. Only components created with createItemComponent are supported.`
     );
   }
-  const { name, defaultValues, propMapper } = config;
-  const contentType = toContentType(name);
-  const count = nextCounter2(counters, `u_content_${contentType}`);
-  const id = makeId(`u_content_${contentType}`, count);
+  const { name, defaultValues, propMapper, slug } = config;
+  const contentType = config.contentType ?? toContentType(name);
+  const metaBase = `u_content_${config.metaName ?? contentType}`;
+  const count = nextCounter2(counters, metaBase);
+  const id = makeId(metaBase, count);
   const { children, ...restProps } = element.props;
   const mappedValues = propMapper({ children, ...restProps });
   const finalValues = mergeValues(defaultValues, mappedValues);
@@ -1972,7 +1976,7 @@ function processItem(element, counters, layout = {}) {
     ...finalValues,
     _meta: {
       htmlID: id,
-      htmlClassNames: `u_content_${contentType}`,
+      htmlClassNames: metaBase,
       ...finalValues._meta || {}
     },
     selectable: true,
@@ -1989,7 +1993,7 @@ function processItem(element, counters, layout = {}) {
     });
     values.src = pinImageSrc(itemSrc, availableWidth);
   }
-  return { type: contentType, values };
+  return slug ? { type: contentType, slug, values } : { type: contentType, values };
 }
 function processColumn(element, counters, layout = {}) {
   const count = nextCounter2(counters, "u_column");
@@ -2133,6 +2137,89 @@ function renderToJson(element) {
   };
 }
 
-export { Body_default as Body, Button_default as Button, Column_default as Column, ColumnLayouts, DEFAULT_CONFIG, Divider_default as Divider, Document, Email, Heading_default as Heading, Html_default as Html, Image_default as Image, Menu_default as Menu, Page, Paragraph_default as Paragraph, Row_default as Row, Social_default as Social, Table_default as Table, UnlayerProvider, Video_default as Video, htmlToTextJson, renderRowToJson, renderToHtml, renderToHtmlParts, renderToJson, renderToPlainText, useUnlayerConfig, validateColumnLayout };
+// src/utils/register-tool.tsx
+function initialValuesFromOptions(options) {
+  const result = {};
+  for (const group of Object.values(options ?? {})) {
+    for (const [property, option] of Object.entries(group?.options ?? {})) {
+      if (!option || option.enabled === false) continue;
+      if (typeof option.defaultValue !== "undefined") {
+        result[property] = option.defaultValue;
+      }
+    }
+  }
+  return result;
+}
+function withSanitizer(exporter) {
+  return (values, ...args) => {
+    const html = String(exporter(values, ...args) ?? "");
+    const meta = args[args.length - 1];
+    const toSafeHtml = meta?.exporterConfig?.toSafeHtml;
+    return typeof toSafeHtml === "function" ? toSafeHtml(html) : html;
+  };
+}
+function withLinkNormalization(exporter, linkKeys) {
+  if (linkKeys.length === 0) return exporter;
+  return (values, ...args) => {
+    const out = { ...values };
+    for (const key of linkKeys) {
+      const normalized = normalizeLinkValue(out[key]);
+      if (normalized !== void 0) out[key] = normalized;
+    }
+    return exporter(out, ...args);
+  };
+}
+function linkWidgetKeys(options) {
+  const keys = [];
+  for (const group of Object.values(options ?? {})) {
+    for (const [key, option] of Object.entries(group?.options ?? {})) {
+      if (option && option.widget === "link") keys.push(key);
+    }
+  }
+  return keys;
+}
+function registerTool(tool) {
+  if (!tool?.name || typeof tool.name !== "string") {
+    throw new Error("[Unlayer] registerTool: `name` is required");
+  }
+  const exporters = tool.renderer?.exporters;
+  if (!exporters || !exporters.web && !exporters.email) {
+    throw new Error(
+      `[Unlayer] registerTool("${tool.name}"): \`renderer.exporters\` needs at least a \`web\` or \`email\` exporter`
+    );
+  }
+  const linkKeys = linkWidgetKeys(tool.options);
+  const sanitized = {};
+  for (const mode of ["web", "email", "document"]) {
+    const exporter = exporters[mode];
+    if (exporter) {
+      sanitized[mode] = withSanitizer(withLinkNormalization(exporter, linkKeys));
+    }
+  }
+  if (!sanitized.web && sanitized.email) sanitized.web = sanitized.email;
+  return createItemComponent({
+    name: tool.name,
+    displayName: tool.displayName ?? tool.name,
+    // Option-group widget defaults seed the values; tool-level `values`
+    // win — the editor's precedence.
+    defaultValues: {
+      ...initialValuesFromOptions(tool.options),
+      ...tool.values ?? {}
+    },
+    // Flat props are the tool's values; `values` is the escape hatch.
+    propMapper: ({ children: _children, values, ...rest }) => ({
+      ...values ?? {},
+      ...rest
+    }),
+    exporters: sanitized,
+    contentType: "custom",
+    slug: tool.name,
+    metaName: `custom_${tool.name}`,
+    head: tool.renderer.head
+  });
+}
+var registerElementsTool = registerTool;
+
+export { Body_default as Body, Button_default as Button, Column_default as Column, ColumnLayouts, DEFAULT_CONFIG, Divider_default as Divider, Document, Email, Heading_default as Heading, Html_default as Html, Image_default as Image, Menu_default as Menu, Page, Paragraph_default as Paragraph, Row_default as Row, Social_default as Social, Table_default as Table, UnlayerProvider, Video_default as Video, htmlToTextJson, registerElementsTool, registerTool, renderRowToJson, renderToHtml, renderToHtmlParts, renderToJson, renderToPlainText, useUnlayerConfig, validateColumnLayout };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map