@dextinity/mail-react 2.0.0-canary-20260729062014

package/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2023, Vivid Planet Software GmbH
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,112 @@
+# @dextinity/mail-react
+
+Single-package solution for building HTML emails with React and MJML. Consumers install only `@dextinity/mail-react` (plus `react`) — never `@faire/mjml-react` directly.
+
+The package:
+
+- re-exports all `@faire/mjml-react` MJML components (with prop types renamed to drop the `I` prefix);
+- extends some of them with extra props and features;
+- adds new components and utilities — block factories (`BlocksBlock`, `ListBlock`, `OneOfBlock`, `OptionalBlock`) for rendering Comet CMS block data, and a `css()` tagged template literal for IDE syntax highlighting.
+
+Some components also ship in an `Html` variant for use inside MJML ending tags. These variants are additive — separate components alongside the `Mjml` versions, with their own API.
+
+## Internal development
+
+We extend `@faire/mjml-react` rather than fork it. A few rules keep that working:
+
+- **Additive only.** A custom component must work everywhere the base did. Only add props — never remove or rename them, and don't require new providers or context. For theme access, prefer `useOptionalTheme()` over `useTheme()`.
+- **Wrap, don't reimplement.** Custom components delegate to `@faire/mjml-react`. Less to maintain, and we stay close to upstream behaviour.
+- **One export per name.** When we ship a custom version, it replaces the re-export. Consumers should never need to import from `@faire/mjml-react` directly.
+- **Public-facing documentation doesn't reference `@faire/mjml-react`.** TSDoc, story descriptions, and changeset entries describe behavior in terms of this package only. Internal places (feature READMEs, commit messages) can mention upstream when it adds maintainer context.
+
+### Styling
+
+- **Inline first.** Components must render correctly without any `<style>` block — clients like Outlook ignore them.
+- **Media queries** via `registerStyles` are progressive enhancement for mobile, where modern CSS (flex, grid) is fine. Use `theme.breakpoints.*.belowMediaQuery` (max-width queries) to target viewports below a breakpoint.
+- **BEM, camelCase blocks.** Block `mjmlSection`, element `mjmlSection__item`, modifier `mjmlSection--indented`. Every component applies its block class and merges any consumer-provided `className` with `clsx`: `clsx("mjmlSection", className)`.
+
+### Theme variants
+
+Themed components expose their styling through the theme: a flat base entry and an optional, consumer-extensible variants map.
+
+- **Base theme entry covers the unstyled use.** Components render from `theme.<component>` when no variant is picked. The `variant` prop is optional; the package ships no built-in variants.
+- **Variants are declared by the consumer.** Variant names are added via TypeScript module augmentation against the variant-name type for that component. A `defaultVariant` on the theme entry makes one of them the implicit pick.
+- **Responsive values appear only inside variants.** Base entries use plain types per property. Variant entries can declare a `ResponsiveValue<T>` — a `{ default, ...overrides }` shape with override keys drawn from `theme.breakpoints`.
+
+### File layout
+
+- **Location.** Custom components live in `src/components/<concern>/` (e.g. `src/components/section/MjmlSection.tsx`).
+- **File order.** Imports → types/props → component → styles. `registerStyles` calls go below the component.
+- **Module format.** ESM only (`type: module`). Use `.js` extensions in imports.
+- **TSDoc.** Short — one line where possible — on exported components and props.
+- **Prop defaults.** Add `@defaultValue` when the default isn't obvious from the type — runtime defaults, and theme-derived ones the consumer can't see in the shipped types.
+- **Phrasing a default.** Name where the value comes from, not the value itself. One theme token: name it in backticks, as in "The theme's `colors.background.content`". Computed from several: name what it depends on, as in "The theme's `divider` height for the active variant".
+- **Defaults on inherited props.** Redeclare the prop locally (`Omit` it from the base, re-add it with the same type) so the tag is on the prop itself. Never document the default in the component's TSDoc.
+
+### Storybook
+
+Every custom component has a story in `src/components/<concern>/__stories__/<Component>.stories.tsx`. Wrap non-section stories in `<MjmlSection indent>` to show a realistic indented layout.
+
+Placeholder images use the `picsum.photos` seed URL pattern — `https://picsum.photos/seed/<seed>/<width>/<height>` — so the same seed renders the same image on every build.
+
+### Changesets
+
+When a custom component replaces a re-export, describe the change against the previous re-export — the added props, features, or behavior. Consumers don't need to know the internal component is new; they only see what's different in the API they use.
+
+## Internal documentation per feature
+
+Features substantial enough to live in their own directory should have a `README.md` that describes the current state and how the feature changes it — and, when a maintainer might assume otherwise, the boundaries it deliberately doesn't cross. These READMEs are internal — written for the people (and agents) maintaining the code, not for consumers. End-user usage docs live elsewhere (see [Consumer-facing documentation](#consumer-facing-documentation)).
+
+### What is a feature
+
+A feature is any self-contained unit of behavior worth describing on its own — a component (`InlineLink`), a utility (`css` helper), an addon (the Storybook addon), or the package itself. Features nest: this README documents `@dextinity/mail-react` as a feature, and the components inside it are features in their own right.
+
+A feature README describes **only its own feature**. It does not describe parent features that contain it, nor sub-features it contains — each of those has its own README.
+
+### Where they live
+
+A feature that warrants a README is organized as a directory, with the README at the directory root (e.g. `src/components/inline-link/README.md`). Small features that live as a single file inside a parent don't need their own README — they're just part of the parent. Promote a file to a directory at the same time you give it a README.
+
+### What goes in a feature README
+
+**Title.** Use the exact identifier when the feature is a single component or function (e.g. `MjmlSection`); otherwise use a sentence-case name (e.g. _Inline link_).
+
+Two sections, in order. Only the intro is required.
+
+1. **Intro.** One short paragraph: the current state, and how the feature changes it. Describe the current state as plain facts — what's there, what's required, what's missing — rather than framing it as "a problem the feature solves". Maintainers read this to work on the code, not to be sold on the feature's existence.
+2. **Non-goals** (optional). Things the feature deliberately doesn't do — only when a reader would reasonably assume it does, typically because the feature's name, its domain, or a sibling feature suggests so. The test: would a maintainer look here for this and be surprised it's missing? If not, leave it out. Skip the obvious; skip future work; skip rejected alternatives — those belong in the commit that made the choice.
+
+    Write each bullet as a noun phrase naming the thing not done (`Not a heading component`, `No CSS variables`). Add a single follow-up sentence only when the reader needs to be redirected to the alternative or told why.
+
+Other sections should be rare — only when content is durable, feature-specific, and doesn't fit the two above. Specifically not warranted: no Architecture (the code shows it), no Design decisions (commits carry them), no Usage (consumer docs), no Dependencies (imports show them; non-obvious cross-feature coupling belongs in the intro).
+
+**Express the rule, not the code.** Every line should say something the code doesn't. Don't restate type signatures, prop lists, formulas, or control flow — the code already shows those.
+
+**Length.** Simple feature → one paragraph. Complex feature → one screen, no scrolling. Past a screen and you're probably duplicating commit history or describing what the code shows.
+
+### Template
+
+```md
+# <feature-name>
+
+<One short paragraph: the current state, and how the feature changes it.>
+
+## Non-goals <!-- only if any -->
+
+- <Noun phrase naming what the feature deliberately doesn't do.> <Optional follow-up sentence pointing to the alternative or stating the rationale.>
+```
+
+### Living documents
+
+Feature READMEs (this one included) should stay current. Update them in the same PR as any change that makes them inaccurate or adds context worth recording.
+
+## Usage documentation
+
+Two artifacts document how to _use_ this package, for two readers:
+
+- **Docs** — [docs/docs/3-features-modules/13-building-html-emails/](../../docs/docs/3-features-modules/13-building-html-emails/) — for people building emails with the package.
+- **Agent skill** — [skills/comet-mail-react/SKILL.md](../../skills/comet-mail-react/SKILL.md) — the same guidance for AI agents working in a project that uses this package.
+
+Both teach the same things: what the package is for, how to build emails with it, the patterns to reach for, and the email-client pitfalls — markup that's fine in a browser can render wrong in clients like Outlook. They differ in one respect — an agent already has the package's types and TSDoc in its project, so the skill doesn't restate type signatures, prop lists, or defaults; those live in the types and TSDoc, and it spends its words on everything they can't convey on their own.
+
+When a change affects how the package is used — components added/removed/renamed, changed behavior, new usage patterns, or styling conventions — update both in the same PR; consider a separate docs commit so reviewers can take them on their own.

package/lib/blocks/factories/BlocksBlock.d.ts

@@ -0,0 +1,14 @@
+import type { SupportedBlocks } from "./types.js";
+interface Props {
+    supportedBlocks: SupportedBlocks;
+    data: {
+        blocks: Array<{
+            key: string;
+            type: string;
+            visible: boolean;
+            props: unknown;
+        }>;
+    };
+}
+export declare const BlocksBlock: ({ supportedBlocks, data: { blocks } }: Props) => import("react/jsx-runtime").JSX.Element;
+export {};

package/lib/blocks/factories/BlocksBlock.js

@@ -0,0 +1,15 @@
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { MjmlText } from "@faire/mjml-react";
+import { Fragment } from "react";
+export const BlocksBlock = ({ supportedBlocks, data: { blocks } }) => {
+    return (_jsx(_Fragment, { children: blocks.map((block) => {
+            const blockFunction = supportedBlocks[block.type];
+            if (!blockFunction) {
+                if (process.env.NODE_ENV === "development") {
+                    return (_jsxs(MjmlText, { children: ["Unknown type (", block.type, "): ", JSON.stringify(block.props)] }, block.key));
+                }
+                return null;
+            }
+            return _jsx(Fragment, { children: blockFunction(block.props) }, block.key);
+        }) }));
+};

package/lib/blocks/factories/ListBlock.d.ts

@@ -0,0 +1,13 @@
+import { type ReactNode } from "react";
+interface Props {
+    block: (props: any) => ReactNode;
+    data: {
+        blocks: Array<{
+            key: string;
+            visible: boolean;
+            props: unknown;
+        }>;
+    };
+}
+export declare const ListBlock: ({ block: blockFunction, data: { blocks } }: Props) => import("react/jsx-runtime").JSX.Element;
+export {};

package/lib/blocks/factories/ListBlock.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { Fragment } from "react";
+export const ListBlock = ({ block: blockFunction, data: { blocks } }) => {
+    return (_jsx(_Fragment, { children: blocks.map((block) => (_jsx(Fragment, { children: blockFunction(block.props) }, block.key))) }));
+};

package/lib/blocks/factories/OneOfBlock.d.ts

@@ -0,0 +1,14 @@
+import type { PropsWithChildren } from "react";
+import type { SupportedBlocks } from "./types.js";
+interface Props extends PropsWithChildren {
+    data: {
+        block?: {
+            type: string;
+            props: any;
+        };
+    };
+    supportedBlocks: SupportedBlocks;
+    className?: string;
+}
+export declare const OneOfBlock: ({ data: { block, ...additionalProps }, supportedBlocks, children, className }: Props) => import("react/jsx-runtime").JSX.Element;
+export {};

package/lib/blocks/factories/OneOfBlock.js

@@ -0,0 +1,15 @@
+import { jsxs as _jsxs, Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { MjmlText } from "@faire/mjml-react";
+export const OneOfBlock = ({ data: { block, ...additionalProps }, supportedBlocks, children, className }) => {
+    if (!block) {
+        return null;
+    }
+    const blockFunction = supportedBlocks[block.type];
+    if (!blockFunction) {
+        if (process.env.NODE_ENV === "development") {
+            return (_jsxs(MjmlText, { children: ["Unknown type (", block.type, "): ", JSON.stringify(block.props)] }));
+        }
+        return null;
+    }
+    return _jsx(_Fragment, { children: blockFunction({ ...block.props, ...additionalProps, children, className }) });
+};

package/lib/blocks/factories/OptionalBlock.d.ts

@@ -0,0 +1,10 @@
+import type { PropsWithChildren, ReactNode } from "react";
+interface Props extends PropsWithChildren {
+    block: (props: any) => ReactNode;
+    data: {
+        visible: boolean;
+        block?: any;
+    };
+}
+export declare const OptionalBlock: ({ block: blockFunction, data: { visible, block }, children }: Props) => import("react/jsx-runtime").JSX.Element;
+export {};

package/lib/blocks/factories/OptionalBlock.js

@@ -0,0 +1,7 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+export const OptionalBlock = ({ block: blockFunction, data: { visible, block }, children }) => {
+    if (!visible || !block) {
+        return null;
+    }
+    return _jsx(_Fragment, { children: blockFunction({ ...block, children }) });
+};

package/lib/blocks/factories/types.d.ts

@@ -0,0 +1,4 @@
+import type { ReactNode } from "react";
+export interface SupportedBlocks {
+    [key: string]: (props: any) => ReactNode | undefined;
+}

package/lib/blocks/factories/types.js

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

package/lib/blocks/helpers/PropsWithData.d.ts

@@ -0,0 +1,3 @@
+export interface PropsWithData<Data = unknown> {
+    data: Data;
+}

package/lib/blocks/helpers/PropsWithData.js

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

package/lib/blocks/pixelImage/HtmlPixelImageBlock.d.ts

@@ -0,0 +1,11 @@
+import type { ComponentProps, ReactNode } from "react";
+import type { PixelImageBlockBaseProps } from "./common.js";
+export type HtmlPixelImageBlockProps = Omit<ComponentProps<"img">, "src" | "width" | "height"> & PixelImageBlockBaseProps;
+/**
+ * Renders a pixel-image from the DAM as a raw `<img>` tag.
+ *
+ * Use within raw HTML context — HTML-only emails or
+ * [MJML ending tags](https://documentation.mjml.io/#ending-tags) like `MjmlRaw`.
+ * For MJML context, use `MjmlPixelImageBlock`.
+ */
+export declare function HtmlPixelImageBlock({ data, width, largestPossibleRenderWidth, aspectRatio, className, ...imgProps }: HtmlPixelImageBlockProps): ReactNode;

package/lib/blocks/pixelImage/HtmlPixelImageBlock.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import clsx from "clsx";
+import { HtmlImage } from "../../components/image/HtmlImage.js";
+import { usePixelImageBlockData } from "./usePixelImageBlockData.js";
+/**
+ * Renders a pixel-image from the DAM as a raw `<img>` tag.
+ *
+ * Use within raw HTML context — HTML-only emails or
+ * [MJML ending tags](https://documentation.mjml.io/#ending-tags) like `MjmlRaw`.
+ * For MJML context, use `MjmlPixelImageBlock`.
+ */
+export function HtmlPixelImageBlock({ data, width, largestPossibleRenderWidth, aspectRatio, className, ...imgProps }) {
+    const imageData = usePixelImageBlockData({ data, defaultRenderWidth: width, largestPossibleRenderWidth, aspectRatio });
+    if (!imageData) {
+        return null;
+    }
+    return (_jsx(HtmlImage, { src: imageData.imageUrl, width: imageData.defaultRenderWidth, height: imageData.desktopImageHeight, alt: imageData.alt, title: imageData.title, className: clsx("htmlPixelImageBlock", className), ...imgProps }));
+}

package/lib/blocks/pixelImage/MjmlPixelImageBlock.d.ts

@@ -0,0 +1,9 @@
+import type { ReactNode } from "react";
+import { type MjmlImageProps } from "../../components/image/MjmlImage.js";
+import type { PixelImageBlockBaseProps } from "./common.js";
+export type MjmlPixelImageBlockProps = Omit<MjmlImageProps, "src" | "width" | "height"> & PixelImageBlockBaseProps;
+/**
+ * Renders a pixel-image from the DAM as `MjmlImage`. Must be placed within an
+ * `MjmlColumn`. For raw HTML context, use `HtmlPixelImageBlock`.
+ */
+export declare function MjmlPixelImageBlock({ data, width, largestPossibleRenderWidth, aspectRatio, className, ...imageProps }: MjmlPixelImageBlockProps): ReactNode;

package/lib/blocks/pixelImage/MjmlPixelImageBlock.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import clsx from "clsx";
+import { MjmlImage } from "../../components/image/MjmlImage.js";
+import { usePixelImageBlockData } from "./usePixelImageBlockData.js";
+/**
+ * Renders a pixel-image from the DAM as `MjmlImage`. Must be placed within an
+ * `MjmlColumn`. For raw HTML context, use `HtmlPixelImageBlock`.
+ */
+export function MjmlPixelImageBlock({ data, width, largestPossibleRenderWidth, aspectRatio, className, ...imageProps }) {
+    const imageData = usePixelImageBlockData({ data, defaultRenderWidth: width, largestPossibleRenderWidth, aspectRatio });
+    if (!imageData) {
+        return null;
+    }
+    return (_jsx(MjmlImage, { src: imageData.imageUrl, width: imageData.defaultRenderWidth, height: imageData.desktopImageHeight, alt: imageData.alt, title: imageData.title, className: clsx("mjmlPixelImageBlock", className), ...imageProps }));
+}

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

@@ -0,0 +1,18 @@
+import type { PixelImageBlockData } from "../../blocks.generated.js";
+export type PixelImageBlockBaseProps = {
+    /** The block data to render. */
+    data: PixelImageBlockData;
+    /** Width at which the image is rendered, in the default/desktop breakpoint. */
+    width: number;
+    /**
+     * Largest possible width the image can be rendered at across breakpoints.
+     * Defaults to `theme.sizes.bodyWidth`. Use this when the image can stretch
+     * wider on a narrower breakpoint than its desktop render width.
+     */
+    largestPossibleRenderWidth?: number;
+    /**
+     * Aspect ratio for the rendered image.
+     * @example "16x9"
+     */
+    aspectRatio?: number | string;
+};

package/lib/blocks/pixelImage/common.js

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

package/lib/blocks/pixelImage/usePixelImageBlockConfig.d.ts

@@ -0,0 +1,5 @@
+import { type PixelImageBlockConfig } from "../../config/ConfigProvider.js";
+/**
+ * Reads `config.pixelImageBlock` from the configuration context and returns it narrowed to non-null.
+ */
+export declare function usePixelImageBlockConfig(): PixelImageBlockConfig;

package/lib/blocks/pixelImage/usePixelImageBlockConfig.js

@@ -0,0 +1,11 @@
+import { useConfig } from "../../config/ConfigProvider.js";
+/**
+ * Reads `config.pixelImageBlock` from the configuration context and returns it narrowed to non-null.
+ */
+export function usePixelImageBlockConfig() {
+    const { pixelImageBlock } = useConfig();
+    if (!pixelImageBlock) {
+        throw new Error("`pixelImageBlock` must be set in `config` on `MjmlMailRoot` or `ConfigProvider` to use the pixel-image configuration.");
+    }
+    return pixelImageBlock;
+}

package/lib/blocks/pixelImage/usePixelImageBlockData.d.ts

@@ -0,0 +1,16 @@
+import type { PixelImageBlockData as PixelImageBlockSourceData } from "../../blocks.generated.js";
+interface UsePixelImageBlockDataProps {
+    data: PixelImageBlockSourceData;
+    defaultRenderWidth: number;
+    largestPossibleRenderWidth?: number;
+    aspectRatio?: number | string;
+}
+interface PixelImageBlockData {
+    imageUrl: string;
+    defaultRenderWidth: number;
+    desktopImageHeight: number;
+    alt: string | undefined;
+    title: string | undefined;
+}
+export declare function usePixelImageBlockData({ data: { damFile, cropArea, urlTemplate }, defaultRenderWidth, largestPossibleRenderWidth: passedLargestPossibleRenderWidth, aspectRatio: passedAspectRatio, }: UsePixelImageBlockDataProps): PixelImageBlockData | null;
+export {};

package/lib/blocks/pixelImage/usePixelImageBlockData.js

@@ -0,0 +1,80 @@
+import { useTheme } from "../../theme/ThemeProvider.js";
+import { usePixelImageBlockConfig } from "./usePixelImageBlockConfig.js";
+export function usePixelImageBlockData({ data: { damFile, cropArea, urlTemplate }, defaultRenderWidth, largestPossibleRenderWidth: passedLargestPossibleRenderWidth, aspectRatio: passedAspectRatio, }) {
+    const theme = useTheme();
+    const { validSizes, baseUrl } = usePixelImageBlockConfig();
+    const largestPossibleRenderWidth = passedLargestPossibleRenderWidth ?? theme.sizes.bodyWidth;
+    if (!damFile?.image) {
+        return null;
+    }
+    const usedCropArea = cropArea ?? damFile.image.cropArea;
+    const aspectRatio = passedAspectRatio !== undefined ? parseAspectRatio(passedAspectRatio) : calculateAspectRatio(damFile.image, usedCropArea);
+    const optimalWidth = getOptimalAllowedImageWidth(validSizes, defaultRenderWidth, largestPossibleRenderWidth);
+    const resolvedImageUrl = generateImageUrl(urlTemplate, optimalWidth, aspectRatio);
+    return {
+        imageUrl: isAbsoluteUrl(resolvedImageUrl) ? resolvedImageUrl : `${baseUrl}${resolvedImageUrl}`,
+        defaultRenderWidth,
+        desktopImageHeight: Math.round(defaultRenderWidth / aspectRatio),
+        alt: damFile.altText,
+        title: damFile.title,
+    };
+}
+function isAbsoluteUrl(url) {
+    return !url.startsWith("/");
+}
+function getOptimalAllowedImageWidth(validSizes, defaultRenderWidth, largestPossibleRenderWidth) {
+    const sortedValidSizes = validSizes.sort((a, b) => a - b);
+    let width = null;
+    const largestPossibleWidth = sortedValidSizes[sortedValidSizes.length - 1];
+    sortedValidSizes.forEach((validWidth) => {
+        if (defaultRenderWidth === largestPossibleRenderWidth) {
+            width = largestPossibleRenderWidth * 2;
+        }
+        else if (!width && validWidth >= defaultRenderWidth * 2) {
+            width = validWidth;
+        }
+    });
+    if (!width) {
+        return largestPossibleWidth;
+    }
+    return width;
+}
+// Copied from `calculateInheritAspectRatio` in `@dextinity/site-react` (`src/image/image.utils.ts`).
+// Keep in sync with the site-react version when changes are made.
+function calculateAspectRatio(image, cropArea) {
+    if (cropArea.focalPoint === "SMART") {
+        return image.width / image.height;
+    }
+    if (cropArea.width === undefined || cropArea.height === undefined) {
+        throw new Error("Missing crop dimensions");
+    }
+    return (cropArea.width * image.width) / (cropArea.height * image.height);
+}
+// Copied from `generateImageUrl` in `@dextinity/site-react` (`src/image/image.utils.ts`).
+// Keep in sync with the site-react version when changes are made.
+function generateImageUrl(urlTemplate, width, aspectRatio) {
+    return urlTemplate.replace("$resizeWidth", String(width)).replace("$resizeHeight", String(Math.ceil(width / aspectRatio)));
+}
+// Copied from `parseAspectRatio` in `@dextinity/site-react` (`src/image/image.utils.ts`).
+// Keep in sync with the site-react version when changes are made.
+function parseAspectRatio(value) {
+    let width;
+    let height;
+    if (typeof value === "string") {
+        [width, height] = value.split(/[x/:]/).map((part) => {
+            const parsed = parseFloat(part);
+            return isNaN(parsed) ? undefined : parsed;
+        });
+        if (width && !height) {
+            height = 1;
+        }
+    }
+    else {
+        width = value;
+        height = 1;
+    }
+    if (!width || !height) {
+        throw new Error(`An error occurred while parsing the aspect ratio: ${value}`);
+    }
+    return width / height;
+}

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;
+};