@unlayer/react-elements 0.1.17 → 0.1.18

package/README.md

@@ -333,6 +333,32 @@ The document shell matches the mode: `<Email>` gets the XHTML transitional docty
 
 If your app owns the document shell (an existing page template, an ESP template, an iframe `srcdoc`), use `renderToHtmlParts` instead — it returns `{ head, body }` chunks for you to place yourself.
 
+## Custom Tools
+
+**A custom tool is the custom component you create.** We keep the editor's term — Custom Tools — because it's the same API across the Builder and Elements, and that shared vocabulary is where the power is: the same definition you pass to the editor's [`unlayer.registerTool`](https://docs.unlayer.com/builder/tools/custom) renders from code too. Elements uses the `renderer.exporters` and `renderer.head` halves of the definition; the editor-only parts (`label`, `icon`, `options`, `Viewer`, `validator`) are accepted and ignored:
+
+```tsx
+import { registerTool, Email, Row, Column, renderToHtml, renderToJson } from '@unlayer/react-elements';
+import { countdownTool } from './countdown-tool'; // the same object you register in the editor
+
+const Countdown = registerTool(countdownTool); // same term, same config as the editor
+
+const tree = (
+  <Email>
+    <Row><Column>
+      <Countdown endTime="2026-08-01T00:00:00Z" digitColor="#e11d48" />
+    </Column></Row>
+  </Email>
+);
+
+renderToHtml(tree);  // renders via YOUR exporters — identical output to editor exports
+renderToJson(tree);  // emits { type: "custom", slug: "countdown", values } — opens in the Builder as the real tool
+```
+
+- Props are the tool's `values` (flat), merged over the definition's defaults; `values={{...}}` works as an escape hatch.
+- Modes fall back like the editor: `document` uses the `web` exporter; an email-only tool renders via its `email` exporter everywhere.
+- **Sanitization:** when your config provides `toSafeHtml`, the tool's HTML output is passed through it (matching editor exports). The default config has no sanitizer — configure one if tool values can contain untrusted content.
+
 ## UnlayerProvider
 
 Configure global settings like CDN base URL, merge tags, text direction, and rendering mode:

package/dist/index.cjs

@@ -620,16 +620,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 {
@@ -682,6 +672,7 @@ function createItemComponent(config) {
       style,
       // Internal props
       index = 0,
+      _metaHtmlId,
       colIndex = 0,
       cells = [],
       bodyValues = {},
@@ -699,11 +690,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
@@ -752,7 +747,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;
 }
@@ -1374,9 +1373,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,
@@ -1385,15 +1387,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}`
                 }
               };
@@ -1564,7 +1564,7 @@ UnlayerProvider.displayName = "UnlayerProvider";
 function useUnlayerConfig() {
   return React.useContext(getUnlayerContext());
 }
-function ensureMeta2(values, type, index = 0) {
+function ensureMeta(values, type, index = 0) {
   return {
     ...values,
     _meta: {
@@ -1645,17 +1645,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 = exporters.heads[name];
+  const valuesWithMeta = ensureMeta(finalValues, contentType, count - 1);
+  const head = config.head ?? exporters.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 = exporters.heads["Column"];
   callHead(columnHead, columnValues, bodyValues, displayMode, headConfig, styles, scripts, tags);
   const children = collectChildren(element.props.children);
@@ -1667,7 +1667,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 = exporters.heads["Row"];
   callHead(rowHead, rowValues, bodyValues, displayMode, headConfig, styles, scripts, tags);
   const children = collectChildren(element.props.children);
@@ -1690,7 +1690,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 = exporters.heads["Body"];
   callHead(bodyHead, bodyValues, bodyValues, displayMode, headConfig, styles, scripts, tags);
   const children = collectChildren(element.props.children);
@@ -1963,10 +1963,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);
@@ -1979,7 +1980,7 @@ function processItem(element, counters, layout = {}) {
     ...finalValues,
     _meta: {
       htmlID: id,
-      htmlClassNames: `u_content_${contentType}`,
+      htmlClassNames: metaBase,
       ...finalValues._meta || {}
     },
     selectable: true,
@@ -1996,7 +1997,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");
@@ -2140,6 +2141,89 @@ function renderToJson(element) {
   };
 }
 
+// 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;
+
 exports.Body = Body_default;
 exports.Button = Button_default;
 exports.Column = Column_default;
@@ -2160,6 +2244,8 @@ exports.Table = Table_default;
 exports.UnlayerProvider = UnlayerProvider;
 exports.Video = Video_default;
 exports.htmlToTextJson = htmlToTextJson;
+exports.registerElementsTool = registerElementsTool;
+exports.registerTool = registerTool;
 exports.renderRowToJson = renderRowToJson;
 exports.renderToHtml = renderToHtml;
 exports.renderToHtmlParts = renderToHtmlParts;