@comet/mail-react 9.0.0-canary-20260707121405 → 9.0.0

package/lib/blocks/richText/common.d.ts

@@ -0,0 +1,66 @@
+import type { ReactNode } from "react";
+import type { TextStyles, VariantName } from "../../theme/themeTypes.js";
+import type { PropsWithData } from "../helpers/PropsWithData.js";
+export interface RichTextBlockData {
+    /** Draft.js raw content state (`{ blocks, entityMap }`), as produced by the CMS RichText block. */
+    draftContent: unknown;
+}
+export type RichTextBlockProps = PropsWithData<RichTextBlockData>;
+/**
+ * Styling for all draft blocks of one type, applied on top of the base theme text styles.
+ *
+ * Style props accept plain values only. For responsive styling, use a theme
+ * variant, or set a `className` and register responsive CSS via `registerStyles`.
+ */
+export type RichTextBlockTypeProps = Omit<TextStyles, "bottomSpacing"> & {
+    /**
+     * The text component's variant to apply, as defined in the theme.
+     *
+     * @defaultValue The theme's `text.defaultVariant`, when set
+     */
+    variant?: VariantName;
+    className?: string;
+};
+/**
+ * Resolves the href of one link block type from the link block's props.
+ *
+ * Return `undefined` to render the linked text without a link.
+ */
+export type RichTextLinkHrefResolver<TProps = unknown> = (props: TProps) => string | undefined;
+/**
+ * Renders the text spanned by one draft-js inline style (e.g. `BOLD`).
+ *
+ * `key` must be set on the returned element's root.
+ */
+export type RichTextInlineRenderer = (children: ReactNode, options: {
+    key: string;
+}) => ReactNode;
+export interface CreateRichTextBlockOptions<TLinkTypes extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Maps draft block types (e.g. `"header-one"`, `"paragraph-standard"`) to the
+     * styling of the text component that renders them.
+     *
+     * Unmapped block types render with the base theme text styles.
+     */
+    blockTypes?: Record<string, RichTextBlockTypeProps>;
+    /**
+     * Maps the application's link block types within `LINK` entities to a
+     * resolver returning the link's href.
+     *
+     * Merged on top of the built-in `external` link type. Link types without
+     * a resolver render their text without a link.
+     */
+    linkTypes?: {
+        [TLinkType in keyof TLinkTypes]: RichTextLinkHrefResolver<TLinkTypes[TLinkType]>;
+    };
+    /**
+     * Maps draft-js inline style names to renderers, keyed by the style name as
+     * it appears in the content's `inlineStyleRanges`.
+     *
+     * Merged on top of the built-in styles (`BOLD`, `ITALIC`, `SUB`, `SUP`,
+     * `STRIKETHROUGH`): use it to override a built-in style, or to render a
+     * custom inline style the application defines in its RTE (e.g. `HIGHLIGHT`),
+     * which has no built-in renderer.
+     */
+    inline?: Record<string, RichTextInlineRenderer>;
+}

package/lib/blocks/richText/common.js

@@ -0,0 +1 @@
+export {};

package/lib/blocks/richText/createRichTextBlock.d.ts

@@ -0,0 +1,30 @@
+import type { ReactNode } from "react";
+import type { CreateRichTextBlockOptions, RichTextBlockProps } from "./common.js";
+/**
+ * Creates a pair of rich-text block components that render CMS RichText block
+ * data (draft-js raw content) as themed text.
+ *
+ * Call the factory once per configuration — at the top level of a file, not
+ * inside a component — and reuse the returned components. Call it again for
+ * differently-configured rich-text blocks (e.g. a generic and a headline-only
+ * one).
+ *
+ * `MjmlRichTextBlock` renders each draft block as `MjmlText` and must be
+ * placed within an `MjmlColumn`. `HtmlRichTextBlock` renders each draft block
+ * as `HtmlText` for raw-HTML contexts (e.g. inside `MjmlRaw`).
+ *
+ * ```ts
+ * export const { MjmlRichTextBlock, HtmlRichTextBlock } = createRichTextBlock({
+ *     blockTypes: {
+ *         "header-one": { variant: "heading1" },
+ *         "paragraph-standard": { variant: "body" },
+ *     },
+ * });
+ * ```
+ */
+export declare function createRichTextBlock<TLinkTypes extends Record<string, unknown> = Record<string, unknown>>(options?: CreateRichTextBlockOptions<TLinkTypes>): {
+    /** Renders CMS RichText block data (draft-js raw content) as one `MjmlText` per draft block. Must be placed within an `MjmlColumn`. */
+    MjmlRichTextBlock: (props: RichTextBlockProps) => ReactNode;
+    /** Renders CMS RichText block data (draft-js raw content) as one `HtmlText` div per draft block, for raw-HTML contexts such as `MjmlRaw`. */
+    HtmlRichTextBlock: (props: RichTextBlockProps) => ReactNode;
+};

package/lib/blocks/richText/createRichTextBlock.js

@@ -0,0 +1,81 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import clsx from "clsx";
+import redraftImport from "redraft";
+import { HtmlText } from "../../components/text/HtmlText.js";
+import { MjmlText } from "../../components/text/MjmlText.js";
+import { builtInLinkTypes, createRichTextRenderers } from "./createRichTextRenderers.js";
+// redraft is CommonJS-only: under native ESM the default import is the whole
+// `module.exports` object, under bundlers it is the render function itself.
+const redraft = typeof redraftImport === "function" ? redraftImport : redraftImport.default;
+function MjmlBlockText({ bottomSpacing, variant, className, fontWeight, children, ...styleProps }) {
+    return (_jsx(MjmlText, { variant: variant, bottomSpacing: bottomSpacing, className: clsx("richTextBlock__text", className), ...(fontWeight !== undefined && { fontWeight: String(fontWeight) }), ...styleProps, children: children }));
+}
+function HtmlBlockText({ bottomSpacing, variant, className, children, ...styleProps }) {
+    return (_jsx(HtmlText, { element: "div", variant: variant, bottomSpacing: bottomSpacing, className: clsx("richTextBlock__text", className), style: styleProps, children: children }));
+}
+function isDraftBlock(block) {
+    if (typeof block !== "object" || block === null || !("key" in block) || !("text" in block)) {
+        return false;
+    }
+    const { key, text } = block;
+    return typeof key === "string" && typeof text === "string";
+}
+function isDraftContent(draftContent) {
+    if (typeof draftContent !== "object" || draftContent === null || !("blocks" in draftContent)) {
+        return false;
+    }
+    const { blocks } = draftContent;
+    return Array.isArray(blocks) && blocks.every(isDraftBlock);
+}
+function renderRichTextContent({ draftContent, blockTypes, linkTypes, inline, blockTextComponent }) {
+    if (!isDraftContent(draftContent)) {
+        return null;
+    }
+    const blocksWithText = draftContent.blocks.filter((block) => block.text !== "");
+    const lastBlockKey = blocksWithText[blocksWithText.length - 1]?.key;
+    if (lastBlockKey === undefined) {
+        return null;
+    }
+    const renderers = createRichTextRenderers({ blockTypes, linkTypes, inline, blockTextComponent, lastBlockKey });
+    return redraft({ ...draftContent, blocks: blocksWithText }, renderers);
+}
+/**
+ * Creates a pair of rich-text block components that render CMS RichText block
+ * data (draft-js raw content) as themed text.
+ *
+ * Call the factory once per configuration — at the top level of a file, not
+ * inside a component — and reuse the returned components. Call it again for
+ * differently-configured rich-text blocks (e.g. a generic and a headline-only
+ * one).
+ *
+ * `MjmlRichTextBlock` renders each draft block as `MjmlText` and must be
+ * placed within an `MjmlColumn`. `HtmlRichTextBlock` renders each draft block
+ * as `HtmlText` for raw-HTML contexts (e.g. inside `MjmlRaw`).
+ *
+ * ```ts
+ * export const { MjmlRichTextBlock, HtmlRichTextBlock } = createRichTextBlock({
+ *     blockTypes: {
+ *         "header-one": { variant: "heading1" },
+ *         "paragraph-standard": { variant: "body" },
+ *     },
+ * });
+ * ```
+ */
+export function createRichTextBlock(options = {}) {
+    const blockTypes = options.blockTypes ?? {};
+    const linkTypes = {
+        ...builtInLinkTypes,
+        // Consumers declare each resolver's props via the typed map, but at
+        // runtime they are unknown draft-js data. This one contained cast lets
+        // consumers work typed without casting in their own resolvers.
+        ...options.linkTypes,
+    };
+    const inline = options.inline ?? {};
+    function MjmlRichTextBlock({ data }) {
+        return renderRichTextContent({ draftContent: data.draftContent, blockTypes, linkTypes, inline, blockTextComponent: MjmlBlockText });
+    }
+    function HtmlRichTextBlock({ data }) {
+        return renderRichTextContent({ draftContent: data.draftContent, blockTypes, linkTypes, inline, blockTextComponent: HtmlBlockText });
+    }
+    return { MjmlRichTextBlock, HtmlRichTextBlock };
+}

package/lib/blocks/richText/createRichTextRenderers.d.ts

@@ -0,0 +1,17 @@
+import type { ComponentType, PropsWithChildren } from "react";
+import type { Renderers } from "redraft";
+import type { RichTextBlockTypeProps, RichTextInlineRenderer, RichTextLinkHrefResolver } from "./common.js";
+export type BlockTextProps = PropsWithChildren<RichTextBlockTypeProps & {
+    /** Whether the theme's spacing below the text applies — set for every draft block except the last. */
+    bottomSpacing: boolean;
+}>;
+export declare const builtInLinkTypes: Record<string, RichTextLinkHrefResolver>;
+interface CreateRichTextRenderersOptions {
+    blockTypes: Record<string, RichTextBlockTypeProps>;
+    linkTypes: Record<string, RichTextLinkHrefResolver>;
+    inline: Record<string, RichTextInlineRenderer>;
+    blockTextComponent: ComponentType<BlockTextProps>;
+    lastBlockKey: string;
+}
+export declare function createRichTextRenderers({ blockTypes, linkTypes, inline, blockTextComponent, lastBlockKey, }: CreateRichTextRenderersOptions): Renderers;
+export {};

package/lib/blocks/richText/createRichTextRenderers.js

@@ -0,0 +1,83 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { HtmlInlineLink } from "../../components/inlineLink/HtmlInlineLink.js";
+const inlineStyleRenderers = {
+    // The explicit styles back up the semantic tags in rendering engines that don't apply their default styling.
+    BOLD: (children, { key }) => (_jsx("strong", { style: { fontWeight: "bold" }, children: children }, key)),
+    ITALIC: (children, { key }) => (_jsx("em", { style: { fontStyle: "italic" }, children: children }, key)),
+    SUB: (children, { key }) => _jsx("sub", { children: children }, key),
+    SUP: (children, { key }) => _jsx("sup", { children: children }, key),
+    STRIKETHROUGH: (children, { key }) => _jsx("s", { children: children }, key),
+};
+function resolveExternalLinkHref(props) {
+    if (typeof props !== "object" || props === null || !("targetUrl" in props)) {
+        return undefined;
+    }
+    const { targetUrl } = props;
+    return typeof targetUrl === "string" ? targetUrl : undefined;
+}
+export const builtInLinkTypes = {
+    external: resolveExternalLinkHref,
+};
+function getLinkBlock(entityData) {
+    if (typeof entityData !== "object" || entityData === null || !("block" in entityData)) {
+        return undefined;
+    }
+    const { block } = entityData;
+    if (typeof block !== "object" || block === null || !("type" in block) || !("props" in block)) {
+        return undefined;
+    }
+    const { type, props } = block;
+    return typeof type === "string" ? { type, props } : undefined;
+}
+function renderWithLineBreaks(node) {
+    if (typeof node === "string" && node.includes("\n")) {
+        const lines = node.split("\n");
+        return lines.flatMap((line, index) => (index === 0 ? [line] : [_jsx("br", {}, index), line]));
+    }
+    if (Array.isArray(node)) {
+        return node.map((child) => renderWithLineBreaks(child));
+    }
+    return node;
+}
+function createTextBlockRenderFn({ blockTextComponent: BlockText, blockTypeProps, lastBlockKey }) {
+    return (children, { keys }) => children.map((child, index) => (_jsx(BlockText, { bottomSpacing: keys[index] !== lastBlockKey, ...blockTypeProps, children: renderWithLineBreaks(child) }, keys[index])));
+}
+function createListBlockRenderFn({ listElement: ListElement, blockTextComponent: BlockText, blockTypeProps, lastBlockKey, }) {
+    return (children, { keys }) => (_jsx(BlockText, { bottomSpacing: !keys.includes(lastBlockKey), ...blockTypeProps, children: _jsx(ListElement, { className: "richTextBlock__list", style: { marginTop: 0, marginBottom: 0 }, children: children.map((child, index) => (_jsx("li", { className: "richTextBlock__listItem", children: renderWithLineBreaks(child) }, keys[index]))) }) }, keys.join("-")));
+}
+const listBlockTypes = ["unordered-list-item", "ordered-list-item"];
+export function createRichTextRenderers({ blockTypes, linkTypes, inline, blockTextComponent, lastBlockKey, }) {
+    const blocks = {};
+    // "unstyled" is redraft's blockFallback: registering it makes every block type the caller did not configure render with base theme styles.
+    for (const blockType of new Set(["unstyled", ...Object.keys(blockTypes)])) {
+        if (listBlockTypes.includes(blockType)) {
+            continue;
+        }
+        blocks[blockType] = createTextBlockRenderFn({ blockTextComponent, blockTypeProps: blockTypes[blockType] ?? {}, lastBlockKey });
+    }
+    for (const listBlockType of listBlockTypes) {
+        blocks[listBlockType] = createListBlockRenderFn({
+            listElement: listBlockType === "unordered-list-item" ? "ul" : "ol",
+            blockTextComponent,
+            blockTypeProps: blockTypes[listBlockType] ?? {},
+            lastBlockKey,
+        });
+    }
+    return {
+        inline: { ...inlineStyleRenderers, ...inline },
+        blocks,
+        entities: {
+            LINK: (children, data, { key }) => {
+                const linkBlock = getLinkBlock(data);
+                if (linkBlock === undefined) {
+                    return children;
+                }
+                const href = linkTypes[linkBlock.type]?.(linkBlock.props);
+                if (href === undefined) {
+                    return children;
+                }
+                return (_jsx(HtmlInlineLink, { className: "richTextBlock__link", href: href, children: children }, key));
+            },
+        },
+    };
+}

package/lib/index.d.ts

@@ -8,6 +8,8 @@ export type { HtmlPixelImageBlockProps } from "./blocks/pixelImage/HtmlPixelImag
 export { HtmlPixelImageBlock } from "./blocks/pixelImage/HtmlPixelImageBlock.js";
 export type { MjmlPixelImageBlockProps } from "./blocks/pixelImage/MjmlPixelImageBlock.js";
 export { MjmlPixelImageBlock } from "./blocks/pixelImage/MjmlPixelImageBlock.js";
+export type { CreateRichTextBlockOptions, RichTextBlockProps } from "./blocks/richText/common.js";
+export { createRichTextBlock } from "./blocks/richText/createRichTextBlock.js";
 export type { HtmlButtonProps } from "./components/button/HtmlButton.js";
 export { HtmlButton } from "./components/button/HtmlButton.js";
 export type { MjmlButtonProps } from "./components/button/MjmlButton.js";

package/lib/index.js

@@ -4,6 +4,7 @@ export { OneOfBlock } from "./blocks/factories/OneOfBlock.js";
 export { OptionalBlock } from "./blocks/factories/OptionalBlock.js";
 export { HtmlPixelImageBlock } from "./blocks/pixelImage/HtmlPixelImageBlock.js";
 export { MjmlPixelImageBlock } from "./blocks/pixelImage/MjmlPixelImageBlock.js";
+export { createRichTextBlock } from "./blocks/richText/createRichTextBlock.js";
 export { HtmlButton } from "./components/button/HtmlButton.js";
 export { MjmlButton } from "./components/button/MjmlButton.js";
 export { HtmlDivider } from "./components/divider/HtmlDivider.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comet/mail-react",
-  "version": "9.0.0-canary-20260707121405",
+  "version": "9.0.0",
   "description": "Utilities for building HTML emails with React",
   "license": "BSD-2-Clause",
   "type": "module",
@@ -23,7 +23,8 @@
     "@faire/mjml-react": "^3.5.4",
     "clsx": "^2.1.1",
     "mjml": "^4.18.0",
-    "mjml-browser": "^4.18.0"
+    "mjml-browser": "^4.18.0",
+    "redraft": "^0.10.2"
   },
   "devDependencies": {
     "@storybook/addon-docs": "^10.3.5",
@@ -47,8 +48,8 @@
     "typescript": "^5.9.3",
     "vite": "^7.3.1",
     "vitest": "^4.1.8",
-    "@comet/cli": "9.0.0-canary-20260707121405",
-    "@comet/eslint-config": "9.0.0-canary-20260707121405"
+    "@comet/eslint-config": "9.0.0",
+    "@comet/cli": "9.0.0"
   },
   "peerDependencies": {
     "react": "^17.0.0 || ^18.0.0 || ^19.0.0",