@comet/mail-react 9.0.0-beta.2 → 9.0.0-beta.4

package/lib/blocks/pixelImage/__stories__/HtmlPixelImageBlock.stories.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MjmlColumn, MjmlRaw } from "@faire/mjml-react";
+import { MjmlMailRoot } from "../../../components/mailRoot/MjmlMailRoot.js";
+import { MjmlSection } from "../../../components/section/MjmlSection.js";
+import { HtmlPixelImageBlock } from "../HtmlPixelImageBlock.js";
+import { exampleBlockData } from "./exampleBlockData.js";
+const config = {
+    title: "Components/Blocks/HtmlPixelImageBlock",
+    component: HtmlPixelImageBlock,
+    tags: ["autodocs"],
+    parameters: {
+        mailRoot: false,
+        docs: {
+            description: {
+                component: "Renders a pixel-image from the DAM as a raw `<img>` tag, for use in HTML-only emails or inside MJML ending tags such as `MjmlRaw`.\n\n_Note: this story may fail to load the actual image when the API fixtures don't include the referenced DAM file._",
+            },
+        },
+    },
+    argTypes: {
+        data: { control: false },
+        aspectRatio: {
+            control: "select",
+            options: ["inherit", "16x9", "4x3", "3x2", "3x1", "2x1", "1x1", "1x2", "1x3", "2x3", "3x4", "9x16"],
+        },
+    },
+    args: {
+        data: exampleBlockData,
+        width: 600,
+    },
+};
+export default config;
+export const Default = {
+    render: (args) => (_jsx(MjmlMailRoot, { config: {
+            pixelImageBlock: {
+                validSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 2560, 3200, 3840],
+                baseUrl: "",
+            },
+        }, children: _jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsx(MjmlRaw, { children: _jsx(HtmlPixelImageBlock, { ...args }) }) }) }) })),
+};
+export const AspectRatioOverride = {
+    parameters: {
+        docs: {
+            description: {
+                story: "Renders the same DAM image at its native aspect ratio and overridden to `16x9`, demonstrating how the `aspectRatio` prop reframes the rendered image without changing the source DAM record.",
+            },
+        },
+    },
+    render: (args) => (_jsx(MjmlMailRoot, { config: {
+            pixelImageBlock: {
+                validSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 2560, 3200, 3840],
+                baseUrl: "",
+            },
+        }, children: _jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsxs(MjmlRaw, { children: [_jsx(HtmlPixelImageBlock, { ...args }), _jsx(HtmlPixelImageBlock, { ...args, aspectRatio: "16x9" })] }) }) }) })),
+};

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

@@ -0,0 +1,7 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { MjmlPixelImageBlock } from "../MjmlPixelImageBlock.js";
+type Story = StoryObj<typeof MjmlPixelImageBlock>;
+declare const config: Meta<typeof MjmlPixelImageBlock>;
+export default config;
+export declare const Default: Story;
+export declare const AspectRatioOverride: Story;

package/lib/blocks/pixelImage/__stories__/MjmlPixelImageBlock.stories.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MjmlColumn } from "@faire/mjml-react";
+import { MjmlMailRoot } from "../../../components/mailRoot/MjmlMailRoot.js";
+import { MjmlSection } from "../../../components/section/MjmlSection.js";
+import { MjmlPixelImageBlock } from "../MjmlPixelImageBlock.js";
+import { exampleBlockData } from "./exampleBlockData.js";
+const config = {
+    title: "Components/Blocks/MjmlPixelImageBlock",
+    component: MjmlPixelImageBlock,
+    tags: ["autodocs"],
+    parameters: {
+        mailRoot: false,
+        docs: {
+            description: {
+                component: "Renders a pixel-image from the DAM as `MjmlImage`. Must be placed within an `MjmlColumn`.\n\n_Note: this story may fail to load the actual image when the API fixtures don't include the referenced DAM file._",
+            },
+        },
+    },
+    argTypes: {
+        data: { control: false },
+        aspectRatio: {
+            control: "select",
+            options: ["inherit", "16x9", "4x3", "3x2", "3x1", "2x1", "1x1", "1x2", "1x3", "2x3", "3x4", "9x16"],
+        },
+    },
+    args: {
+        data: exampleBlockData,
+        width: 600,
+    },
+};
+export default config;
+export const Default = {
+    render: (args) => (_jsx(MjmlMailRoot, { config: {
+            pixelImageBlock: {
+                validSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 2560, 3200, 3840],
+                baseUrl: "",
+            },
+        }, children: _jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsx(MjmlPixelImageBlock, { ...args }) }) }) })),
+};
+export const AspectRatioOverride = {
+    parameters: {
+        docs: {
+            description: {
+                story: "Renders the same DAM image at its native aspect ratio and overridden to `16x9`, demonstrating how the `aspectRatio` prop reframes the rendered image without changing the source DAM record.",
+            },
+        },
+    },
+    render: (args) => (_jsx(MjmlMailRoot, { config: {
+            pixelImageBlock: {
+                validSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 2560, 3200, 3840],
+                baseUrl: "",
+            },
+        }, children: _jsx(MjmlSection, { indent: true, children: _jsxs(MjmlColumn, { children: [_jsx(MjmlPixelImageBlock, { ...args }), _jsx(MjmlPixelImageBlock, { ...args, aspectRatio: "16x9" })] }) }) })),
+};

package/lib/blocks/pixelImage/__stories__/exampleBlockData.d.ts

@@ -0,0 +1,2 @@
+import type { PixelImageBlockData } from "../../../blocks.generated.js";
+export declare const exampleBlockData: PixelImageBlockData;

package/lib/blocks/pixelImage/__stories__/exampleBlockData.js

@@ -0,0 +1,19 @@
+export const exampleBlockData = {
+    damFile: {
+        id: "example-image",
+        name: "example-image.jpg",
+        size: 1000000,
+        mimetype: "image/jpeg",
+        contentHash: "example-hash",
+        archived: false,
+        scope: { domain: "at" },
+        fileUrl: "https://picsum.photos/seed/comet-pixel-image/1000/1000",
+        image: {
+            width: 1000,
+            height: 1000,
+            cropArea: { focalPoint: "SMART" },
+            dominantColor: "#000000",
+        },
+    },
+    urlTemplate: "https://picsum.photos/seed/comet-pixel-image/$resizeWidth/$resizeHeight",
+};

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

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

package/lib/blocks/pixelImage/__tests__/usePixelImageBlockConfig.test.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { ConfigProvider } from "../../../config/ConfigProvider.js";
+import { usePixelImageBlockConfig } from "../usePixelImageBlockConfig.js";
+function ConfigProbe() {
+    usePixelImageBlockConfig();
+    return null;
+}
+describe("usePixelImageBlockConfig", () => {
+    it("throws when config.pixelImageBlock is unset", () => {
+        expect(() => renderToStaticMarkup(_jsx(ConfigProbe, {}))).toThrowError(/`pixelImageBlock` must be set/);
+    });
+    it("error message points at MjmlMailRoot and ConfigProvider", () => {
+        expect(() => renderToStaticMarkup(_jsx(ConfigProbe, {}))).toThrowError(/MjmlMailRoot/);
+        expect(() => renderToStaticMarkup(_jsx(ConfigProbe, {}))).toThrowError(/ConfigProvider/);
+    });
+    it("does not throw when config.pixelImageBlock is provided", () => {
+        expect(() => renderToStaticMarkup(_jsx(ConfigProvider, { config: { pixelImageBlock: { validSizes: [640, 1280], baseUrl: "http://localhost:3000" } }, children: _jsx(ConfigProbe, {}) }))).not.toThrow();
+    });
+});

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

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

package/lib/blocks/pixelImage/__tests__/usePixelImageBlockData.test.js

@@ -0,0 +1,205 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { ConfigProvider } from "../../../config/ConfigProvider.js";
+import { createTheme } from "../../../theme/createTheme.js";
+import { ThemeProvider } from "../../../theme/ThemeProvider.js";
+import { usePixelImageBlockData } from "../usePixelImageBlockData.js";
+function captureUsePixelImageData({ data, defaultRenderWidth, largestPossibleRenderWidth, aspectRatio, config }) {
+    const captured = { value: undefined };
+    function Probe() {
+        captured.value = usePixelImageBlockData({ data, defaultRenderWidth, largestPossibleRenderWidth, aspectRatio });
+        return null;
+    }
+    renderToStaticMarkup(_jsx(ThemeProvider, { theme: createTheme(), children: _jsx(ConfigProvider, { config: config, children: _jsx(Probe, {}) }) }));
+    if (captured.value === undefined) {
+        throw new Error("Probe did not run");
+    }
+    return captured.value;
+}
+function expectNonNull(value) {
+    if (value === null) {
+        throw new Error("Expected non-null result from usePixelImageBlockData");
+    }
+    return value;
+}
+const validSizes = [320, 640, 1280, 2048];
+const baseUrl = "http://localhost:3000";
+const config = { pixelImageBlock: { validSizes, baseUrl } };
+const smartUrlTemplate = "/dam/images/abc/resize:$resizeWidth:$resizeHeight/photo.jpg";
+const smartImageData = {
+    damFile: {
+        id: "id-1",
+        name: "photo.jpg",
+        size: 1000,
+        mimetype: "image/jpeg",
+        contentHash: "hash",
+        archived: false,
+        fileUrl: "/dam/files/id-1.jpg",
+        image: {
+            width: 4000,
+            height: 2000,
+            cropArea: { focalPoint: "SMART" },
+        },
+    },
+    urlTemplate: smartUrlTemplate,
+};
+describe("usePixelImageBlockData — width selection", () => {
+    it("picks the smallest validSizes entry >= defaultRenderWidth × 2", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 200, config }));
+        expect(result.imageUrl).toContain(":640:");
+    });
+    it("picks an exact validSizes match when present", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 320, config }));
+        expect(result.imageUrl).toContain(":640:");
+    });
+    it("falls back to the largest validSizes entry when none qualifies", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 2000, config }));
+        expect(result.imageUrl).toContain(":2048:");
+    });
+    it("uses largestPossibleRenderWidth × 2 when defaultRenderWidth equals largestPossibleRenderWidth", () => {
+        const result = expectNonNull(captureUsePixelImageData({
+            data: smartImageData,
+            defaultRenderWidth: 600,
+            largestPossibleRenderWidth: 600,
+            config,
+        }));
+        expect(result.imageUrl).toContain(":1200:");
+    });
+    it("defaults largestPossibleRenderWidth to theme.sizes.bodyWidth (600) and triggers DPR-2 fixed path at width 600", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 600, config }));
+        expect(result.imageUrl).toContain(":1200:");
+    });
+});
+describe("usePixelImageBlockData — URL prefixing", () => {
+    it("prefixes a relative URL with config.pixelImageBlock.baseUrl", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 200, config }));
+        expect(result.imageUrl.startsWith(`${baseUrl}/dam/images/abc/`)).toBe(true);
+    });
+    it("does not prefix an absolute URL", () => {
+        const absoluteData = {
+            ...smartImageData,
+            urlTemplate: "https://cdn.example.com/$resizeWidth/$resizeHeight/photo.jpg",
+        };
+        const result = expectNonNull(captureUsePixelImageData({ data: absoluteData, defaultRenderWidth: 200, config }));
+        expect(result.imageUrl.startsWith("https://cdn.example.com/")).toBe(true);
+        expect(result.imageUrl.includes(baseUrl)).toBe(false);
+    });
+});
+describe("usePixelImageBlockData — aspect ratio", () => {
+    it("uses the natural image aspect ratio for SMART crop areas", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 200, config }));
+        expect(result.desktopImageHeight).toBe(100);
+        expect(result.imageUrl).toContain(":640:320/");
+    });
+    it("derives aspect ratio from crop dimensions for non-SMART crop areas", () => {
+        const nonSmartData = {
+            damFile: {
+                id: "id-2",
+                name: "photo2.jpg",
+                size: 1000,
+                mimetype: "image/jpeg",
+                contentHash: "hash",
+                archived: false,
+                fileUrl: "/dam/files/id-2.jpg",
+                image: {
+                    width: 4000,
+                    height: 2000,
+                    cropArea: { focalPoint: "CENTER", width: 50, height: 100, x: 25, y: 0 },
+                },
+            },
+            urlTemplate: smartUrlTemplate,
+        };
+        const result = expectNonNull(captureUsePixelImageData({ data: nonSmartData, defaultRenderWidth: 200, config }));
+        expect(result.desktopImageHeight).toBe(200);
+        expect(result.imageUrl).toContain(":640:640/");
+    });
+    it("throws when crop dimensions are missing on a non-SMART crop area", () => {
+        const malformedData = {
+            damFile: {
+                id: "id-3",
+                name: "photo3.jpg",
+                size: 1000,
+                mimetype: "image/jpeg",
+                contentHash: "hash",
+                archived: false,
+                fileUrl: "/dam/files/id-3.jpg",
+                image: {
+                    width: 4000,
+                    height: 2000,
+                    cropArea: { focalPoint: "CENTER" },
+                },
+            },
+            urlTemplate: smartUrlTemplate,
+        };
+        expect(() => captureUsePixelImageData({ data: malformedData, defaultRenderWidth: 200, config })).toThrow(/Missing crop dimensions/);
+    });
+});
+describe("usePixelImageBlockData — aspectRatio override", () => {
+    it("uses a numeric aspectRatio in place of the cropArea-derived ratio", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 200, aspectRatio: 16 / 9, config }));
+        expect(result.imageUrl).toContain(":640:360/");
+        expect(result.desktopImageHeight).toBe(113);
+    });
+    it.each([
+        ["WxH", "16x9"],
+        ["W:H", "16:9"],
+        ["W/H", "16/9"],
+    ])("parses string aspectRatio in %s form", (_label, value) => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 200, aspectRatio: value, config }));
+        expect(result.imageUrl).toContain(":640:360/");
+        expect(result.desktopImageHeight).toBe(113);
+    });
+    it("treats a single-token string as `width / 1`", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 200, aspectRatio: "2", config }));
+        expect(result.imageUrl).toContain(":640:320/");
+        expect(result.desktopImageHeight).toBe(100);
+    });
+    it("overrides a non-SMART cropArea ratio", () => {
+        const nonSmartData = {
+            damFile: {
+                id: "id-override",
+                name: "photo.jpg",
+                size: 1000,
+                mimetype: "image/jpeg",
+                contentHash: "hash",
+                archived: false,
+                fileUrl: "/dam/files/id-override.jpg",
+                image: {
+                    width: 4000,
+                    height: 2000,
+                    cropArea: { focalPoint: "CENTER", width: 50, height: 100, x: 25, y: 0 },
+                },
+            },
+            urlTemplate: smartUrlTemplate,
+        };
+        const result = expectNonNull(captureUsePixelImageData({ data: nonSmartData, defaultRenderWidth: 200, aspectRatio: "16x9", config }));
+        expect(result.imageUrl).toContain(":640:360/");
+        expect(result.desktopImageHeight).toBe(113);
+    });
+    it("throws when the aspectRatio string is malformed", () => {
+        expect(() => captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 200, aspectRatio: "not-a-ratio", config })).toThrow(/An error occurred while parsing the aspect ratio: not-a-ratio/);
+    });
+});
+describe("usePixelImageBlockData — incomplete data", () => {
+    it("returns null when damFile is absent", () => {
+        const result = captureUsePixelImageData({ data: { urlTemplate: smartUrlTemplate }, defaultRenderWidth: 200, config });
+        expect(result).toBeNull();
+    });
+    it("returns null when damFile.image is absent", () => {
+        const noImageData = {
+            damFile: {
+                id: "id-4",
+                name: "no-image.jpg",
+                size: 0,
+                mimetype: "image/jpeg",
+                contentHash: "hash",
+                archived: false,
+                fileUrl: "/dam/files/id-4.jpg",
+            },
+            urlTemplate: smartUrlTemplate,
+        };
+        const result = captureUsePixelImageData({ data: noImageData, defaultRenderWidth: 200, config });
+        expect(result).toBeNull();
+    });
+});

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 `@comet/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 `@comet/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 `@comet/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/client/renderMailHtml.d.ts

@@ -1,5 +1,5 @@
 import mjml2html from "mjml-browser";
-import { type ReactElement } from "react";
+import type { ReactElement } from "react";
 type MjmlOptions = Parameters<typeof mjml2html>[1];
 type MjmlWarning = ReturnType<typeof mjml2html>["errors"][number];
 export declare function renderMailHtml(element: ReactElement, options?: MjmlOptions): {

package/lib/components/mailRoot/MjmlMailRoot.d.ts

@@ -1,4 +1,5 @@
 import type { PropsWithChildren, ReactNode } from "react";
+import { type Config } from "../../config/ConfigProvider.js";
 import type { Theme } from "../../theme/themeTypes.js";
 type MjmlMailRootProps = PropsWithChildren<{
     /**
@@ -6,17 +7,25 @@ type MjmlMailRootProps = PropsWithChildren<{
      * (equivalent to `createTheme()`) is used.
      */
     theme?: Theme;
+    /** Extra content appended inside the built-in `<MjmlAttributes>`, after the default `<MjmlAll>`. */
+    attributes?: ReactNode;
+    /** Extra content appended inside `<MjmlHead>`, after the registered styles block. */
+    head?: ReactNode;
+    /**
+     * Configuration to make available to descendants via `useConfig`.
+     */
+    config?: Config;
 }>;
 /**
  * The root element for email templates. Renders the standard MJML email skeleton
  * (`<Mjml>`, `<MjmlHead>`, `<MjmlBody>`) with `<MjmlAll padding={0} />` as the
  * default attribute so all components start with zero padding.
  *
- * Accepts an optional `theme` prop that controls the body width and responsive
- * breakpoints. The theme is made available to all descendant components via
- * `useTheme()`.
+ * Accepts an optional `theme` prop that controls the body width and responsive breakpoints. The theme is made available to all descendant components via `useTheme()`.
+ *
+ * Accepts an optional `config` prop containing configuration. When provided, the value is made available to descendants via `useConfig()`.
  *
  * Direct children should be section-level components (e.g. `MjmlSection`).
  */
-export declare function MjmlMailRoot({ theme: themeProp, children }: MjmlMailRootProps): ReactNode;
+export declare function MjmlMailRoot({ theme: themeProp, attributes, head, config, children }: MjmlMailRootProps): ReactNode;
 export {};

package/lib/components/mailRoot/MjmlMailRoot.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Mjml, MjmlAll, MjmlAttributes, MjmlBody, MjmlBreakpoint, MjmlHead } from "@faire/mjml-react";
+import { ConfigProvider } from "../../config/ConfigProvider.js";
 import { Styles } from "../../styles/Styles.js";
 import { createTheme } from "../../theme/createTheme.js";
 import { ThemeProvider } from "../../theme/ThemeProvider.js";
@@ -8,13 +9,17 @@ import { ThemeProvider } from "../../theme/ThemeProvider.js";
  * (`<Mjml>`, `<MjmlHead>`, `<MjmlBody>`) with `<MjmlAll padding={0} />` as the
  * default attribute so all components start with zero padding.
  *
- * Accepts an optional `theme` prop that controls the body width and responsive
- * breakpoints. The theme is made available to all descendant components via
- * `useTheme()`.
+ * Accepts an optional `theme` prop that controls the body width and responsive breakpoints. The theme is made available to all descendant components via `useTheme()`.
+ *
+ * Accepts an optional `config` prop containing configuration. When provided, the value is made available to descendants via `useConfig()`.
  *
  * Direct children should be section-level components (e.g. `MjmlSection`).
  */
-export function MjmlMailRoot({ theme: themeProp, children }) {
+export function MjmlMailRoot({ theme: themeProp, attributes, head, config, children }) {
     const theme = themeProp ?? createTheme();
-    return (_jsx(ThemeProvider, { theme: theme, children: _jsxs(Mjml, { children: [_jsxs(MjmlHead, { children: [_jsx(MjmlAttributes, { children: _jsx(MjmlAll, { padding: "0", fontFamily: theme.text.fontFamily }) }), _jsx(MjmlBreakpoint, { width: `${theme.breakpoints.mobile.value}px` }), _jsx(Styles, {})] }), _jsx(MjmlBody, { width: theme.sizes.bodyWidth, backgroundColor: theme.colors.background.body, children: children })] }) }));
+    const content = (_jsx(ThemeProvider, { theme: theme, children: _jsxs(Mjml, { children: [_jsxs(MjmlHead, { children: [_jsxs(MjmlAttributes, { children: [_jsx(MjmlAll, { padding: "0", fontFamily: theme.text.fontFamily }), attributes] }), _jsx(MjmlBreakpoint, { width: `${theme.breakpoints.mobile.value}px` }), _jsx(Styles, {}), head] }), _jsx(MjmlBody, { width: theme.sizes.bodyWidth, backgroundColor: theme.colors.background.body, children: children })] }) }));
+    if (config) {
+        return _jsx(ConfigProvider, { config: config, children: content });
+    }
+    return content;
 }

package/lib/components/section/MjmlSection.d.ts

@@ -11,5 +11,5 @@ export type MjmlSectionProps = IMjmlSectionProps & {
         group?: Partial<IMjmlGroupProps>;
     };
 };
-/** A section wrapper for email layouts. Must be a direct child of `MjmlBody`. */
+/** A section wrapper for email layouts. Must be a direct child of `MjmlBody` or `MjmlWrapper`. */
 export declare function MjmlSection({ children, indent, disableResponsiveBehavior, slotProps, className, ...restProps }: MjmlSectionProps): ReactNode;

package/lib/components/section/MjmlSection.js

@@ -5,12 +5,14 @@ import { registerStyles } from "../../styles/registerStyles.js";
 import { getDefaultFromResponsiveValue, getResponsiveOverrides } from "../../theme/responsiveValue.js";
 import { useOptionalTheme } from "../../theme/ThemeProvider.js";
 import { css } from "../../utils/css.js";
-/** A section wrapper for email layouts. Must be a direct child of `MjmlBody`. */
+import { useIsInsideMjmlWrapper } from "../wrapper/InsideMjmlWrapperContext.js";
+/** A section wrapper for email layouts. Must be a direct child of `MjmlBody` or `MjmlWrapper`. */
 export function MjmlSection({ children, indent, disableResponsiveBehavior, slotProps, className, ...restProps }) {
     const theme = useOptionalTheme();
+    const isInsideWrapper = useIsInsideMjmlWrapper();
     const indentProps = indent ? getIndentProps(theme) : {};
     const resolvedClassName = clsx("mjmlSection", indent && "mjmlSection--indented", className);
-    const themeBackgroundProps = theme ? { backgroundColor: theme.colors.background.content } : {};
+    const themeBackgroundProps = theme && !isInsideWrapper ? { backgroundColor: theme.colors.background.content } : {};
     return (_jsx(BaseMjmlSection, { className: resolvedClassName, ...themeBackgroundProps, ...indentProps, ...restProps, children: disableResponsiveBehavior ? _jsx(MjmlGroup, { ...slotProps?.group, children: children }) : _jsx(_Fragment, { children: children }) }));
 }
 function getIndentProps(theme) {
@@ -24,13 +26,15 @@ function getIndentProps(theme) {
 }
 registerStyles((theme) => {
     const overrides = getResponsiveOverrides(theme.sizes.contentIndentation);
-    if (overrides.length === 0)
+    if (overrides.length === 0) {
         return css ``;
+    }
     return overrides
         .map((override) => {
         const breakpoint = theme.breakpoints[override.breakpointKey];
-        if (!breakpoint)
+        if (!breakpoint) {
             return "";
+        }
         return css `
                 ${breakpoint.belowMediaQuery} {
                     .mjmlSection--indented > table > tbody > tr > td {

package/lib/components/text/HtmlText.d.ts

@@ -1,4 +1,4 @@
-import { type ComponentPropsWithoutRef, type JSX, type ReactNode, type TdHTMLAttributes } from "react";
+import type { ComponentPropsWithoutRef, JSX, ReactNode, TdHTMLAttributes } from "react";
 import type { VariantName } from "../../theme/themeTypes.js";
 interface HtmlTextOwnProps {
     /**