@comet/mail-react 9.0.0-beta.3 → 9.0.0-beta.5

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/components/divider/HtmlDivider.d.ts

@@ -0,0 +1,9 @@
+import type { ReactNode } from "react";
+import type { Theme } from "../../theme/themeTypes.js";
+import type { DividerProps } from "./dividerProps.js";
+export type HtmlDividerProps = DividerProps;
+/**
+ * Themed divider for use inside MJML ending tags or outside of the MJML context.
+ */
+export declare function HtmlDivider({ variant: variantProp, height: heightProp, backgroundColor: backgroundColorProp, backgroundImage: backgroundImageProp, className, style, }: HtmlDividerProps): ReactNode;
+export declare function generateHtmlDividerStyles(theme: Theme): string;

package/lib/components/divider/HtmlDivider.js

@@ -0,0 +1,43 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import clsx from "clsx";
+import { registerStyles } from "../../styles/registerStyles.js";
+import { getDefaultOrUndefined } from "../../theme/responsiveValue.js";
+import { useOptionalTheme } from "../../theme/ThemeProvider.js";
+import { defaultDividerStyles } from "./defaultDividerStyles.js";
+import { generateResponsiveDividerCss } from "./generateResponsiveDividerCss.js";
+// U+200B keeps the cell from collapsing in clients that drop empty <td>s,
+// without contributing visible width.
+const zeroWidthSpace = String.fromCharCode(0x200b);
+/**
+ * Themed divider for use inside MJML ending tags or outside of the MJML context.
+ */
+export function HtmlDivider({ variant: variantProp, height: heightProp, backgroundColor: backgroundColorProp, backgroundImage: backgroundImageProp, className, style, }) {
+    const theme = useOptionalTheme();
+    if (theme === null && variantProp !== undefined) {
+        throw new Error("The `variant` prop requires being wrapped in a ThemeProvider or MjmlMailRoot.");
+    }
+    const themeDivider = theme?.divider ?? defaultDividerStyles;
+    const { defaultVariant, variants, ...baseStyles } = themeDivider;
+    const activeVariant = variantProp ?? defaultVariant;
+    const variantStyles = activeVariant ? variants?.[activeVariant] : undefined;
+    const mergedStyles = variantStyles ? { ...baseStyles, ...variantStyles } : baseStyles;
+    const height = heightProp ?? getDefaultOrUndefined(mergedStyles.height);
+    const backgroundColor = backgroundColorProp ?? getDefaultOrUndefined(mergedStyles.backgroundColor);
+    const backgroundImage = backgroundImageProp ?? getDefaultOrUndefined(mergedStyles.backgroundImage);
+    const dividerStyle = {
+        height,
+        lineHeight: height === undefined ? undefined : `${height}px`,
+        fontSize: 0,
+        backgroundColor,
+        backgroundImage,
+        ...{ msoLineHeightRule: "exactly" },
+        ...style,
+    };
+    return (_jsx("table", { role: "presentation", cellPadding: 0, cellSpacing: 0, border: 0, width: "100%", className: clsx("htmlDivider", activeVariant && `htmlDivider--${activeVariant}`, className), children: _jsx("tbody", { children: _jsx("tr", { children: _jsx("td", { bgcolor: backgroundColor, height: height, style: dividerStyle, children: zeroWidthSpace }) }) }) }));
+}
+export function generateHtmlDividerStyles(theme) {
+    return generateResponsiveDividerCss(theme, {
+        styleSelector: (variantName) => `.htmlDivider--${variantName} td`,
+    });
+}
+registerStyles(generateHtmlDividerStyles);

package/lib/components/divider/MjmlDivider.d.ts

@@ -0,0 +1,7 @@
+import type { ReactNode } from "react";
+import type { DividerProps } from "./dividerProps.js";
+export type MjmlDividerProps = DividerProps;
+/**
+ * Themed divider for use inside an `MjmlColumn`.
+ */
+export declare function MjmlDivider({ variant, height, backgroundColor, backgroundImage, className, style }: MjmlDividerProps): ReactNode;

package/lib/components/divider/MjmlDivider.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { MjmlRaw } from "@faire/mjml-react";
+import clsx from "clsx";
+import { useOptionalTheme } from "../../theme/ThemeProvider.js";
+import { HtmlDivider } from "./HtmlDivider.js";
+/**
+ * Themed divider for use inside an `MjmlColumn`.
+ */
+export function MjmlDivider({ variant, height, backgroundColor, backgroundImage, className, style }) {
+    const theme = useOptionalTheme();
+    const activeVariant = variant ?? theme?.divider.defaultVariant;
+    return (_jsx(MjmlRaw, { children: _jsx(HtmlDivider, { variant: variant, height: height, backgroundColor: backgroundColor, backgroundImage: backgroundImage, className: clsx("mjmlDivider", activeVariant && `mjmlDivider--${activeVariant}`, className), style: style }) }));
+}

package/lib/components/divider/__stories__/HtmlDivider.stories.d.ts

@@ -0,0 +1,10 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { HtmlDivider } from "../HtmlDivider.js";
+type Story = StoryObj<typeof HtmlDivider>;
+declare const config: Meta<typeof HtmlDivider>;
+export default config;
+export declare const Default: Story;
+export declare const CustomHeightAndColor: Story;
+export declare const WithTheme: Story;
+export declare const WithVariants: Story;
+export declare const GradientWithFallback: Story;

package/lib/components/divider/__stories__/HtmlDivider.stories.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MjmlColumn, MjmlRaw, MjmlSpacer } from "@faire/mjml-react";
+import { createTheme } from "../../../theme/createTheme.js";
+import { MjmlSection } from "../../section/MjmlSection.js";
+import { HtmlDivider } from "../HtmlDivider.js";
+const config = {
+    title: "Components/HtmlDivider",
+    component: HtmlDivider,
+    tags: ["autodocs"],
+    argTypes: {
+        variant: { control: "text" },
+        height: { control: "number" },
+        backgroundColor: { control: "text" },
+        backgroundImage: { control: "text" },
+        className: { control: "text" },
+        style: { control: false },
+    },
+    render: (args) => (_jsx(MjmlSection, { indent: true, children: _jsxs(MjmlColumn, { children: [_jsx(MjmlSpacer, { height: "16px" }), _jsx(MjmlRaw, { children: _jsx(HtmlDivider, { ...args }) }), _jsx(MjmlSpacer, { height: "16px" })] }) })),
+};
+export default config;
+export const Default = {};
+export const CustomHeightAndColor = {
+    args: {
+        height: 8,
+        backgroundColor: "#FF6B6B",
+    },
+};
+export const WithTheme = {
+    parameters: {
+        theme: createTheme({
+            divider: {
+                height: 2,
+                backgroundColor: "#5B4FC7",
+            },
+        }),
+    },
+};
+export const WithVariants = {
+    parameters: {
+        theme: createTheme({
+            divider: {
+                defaultVariant: "thin",
+                variants: {
+                    thin: { height: 1, backgroundColor: "#999999" },
+                    thick: { height: { default: 12, mobile: 8 }, backgroundColor: "#222222" },
+                },
+            },
+        }),
+    },
+    render: (args) => (_jsx(MjmlSection, { indent: true, children: _jsxs(MjmlColumn, { children: [_jsx(MjmlSpacer, { height: "16px" }), _jsx(MjmlRaw, { children: _jsx(HtmlDivider, { ...args }) }), _jsx(MjmlSpacer, { height: "16px" }), _jsx(MjmlRaw, { children: _jsx(HtmlDivider, { ...args, variant: "thick" }) }), _jsx(MjmlSpacer, { height: "16px" })] }) })),
+};
+export const GradientWithFallback = {
+    // `backgroundColor` is the solid fallback for clients that
+    // don't render `background-image` (notably older Outlook).
+    args: {
+        height: 6,
+        backgroundColor: "#5B4FC7",
+        backgroundImage: "linear-gradient(to right, #5B4FC7, #FF6B6B, #FFD166)",
+    },
+};

package/lib/components/divider/__stories__/MjmlDivider.stories.d.ts

@@ -0,0 +1,10 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { MjmlDivider } from "../MjmlDivider.js";
+type Story = StoryObj<typeof MjmlDivider>;
+declare const config: Meta<typeof MjmlDivider>;
+export default config;
+export declare const Default: Story;
+export declare const CustomHeightAndColor: Story;
+export declare const WithTheme: Story;
+export declare const WithVariants: Story;
+export declare const GradientWithFallback: Story;

package/lib/components/divider/__stories__/MjmlDivider.stories.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MjmlColumn, MjmlSpacer } from "@faire/mjml-react";
+import { createTheme } from "../../../theme/createTheme.js";
+import { MjmlSection } from "../../section/MjmlSection.js";
+import { MjmlDivider } from "../MjmlDivider.js";
+const config = {
+    title: "Components/MjmlDivider",
+    component: MjmlDivider,
+    tags: ["autodocs"],
+    argTypes: {
+        variant: { control: "text" },
+        height: { control: "number" },
+        backgroundColor: { control: "text" },
+        backgroundImage: { control: "text" },
+        className: { control: "text" },
+        style: { control: false },
+    },
+    render: (args) => (_jsx(MjmlSection, { indent: true, children: _jsxs(MjmlColumn, { children: [_jsx(MjmlSpacer, { height: "16px" }), _jsx(MjmlDivider, { ...args }), _jsx(MjmlSpacer, { height: "16px" })] }) })),
+};
+export default config;
+export const Default = {};
+export const CustomHeightAndColor = {
+    args: {
+        height: 8,
+        backgroundColor: "#FF6B6B",
+    },
+};
+export const WithTheme = {
+    parameters: {
+        theme: createTheme({
+            divider: {
+                height: 2,
+                backgroundColor: "#5B4FC7",
+            },
+        }),
+    },
+};
+export const WithVariants = {
+    parameters: {
+        theme: createTheme({
+            divider: {
+                defaultVariant: "thin",
+                variants: {
+                    thin: { height: 1, backgroundColor: "#999999" },
+                    thick: { height: { default: 12, mobile: 8 }, backgroundColor: "#222222" },
+                },
+            },
+        }),
+    },
+    render: (args) => (_jsx(MjmlSection, { indent: true, children: _jsxs(MjmlColumn, { children: [_jsx(MjmlSpacer, { height: "16px" }), _jsx(MjmlDivider, { ...args }), _jsx(MjmlSpacer, { height: "16px" }), _jsx(MjmlDivider, { ...args, variant: "thick" }), _jsx(MjmlSpacer, { height: "16px" })] }) })),
+};
+export const GradientWithFallback = {
+    // `backgroundColor` is the solid fallback for clients that
+    // don't render `background-image` (notably older Outlook).
+    args: {
+        height: 6,
+        backgroundColor: "#5B4FC7",
+        backgroundImage: "linear-gradient(to right, #5B4FC7, #FF6B6B, #FFD166)",
+    },
+};

package/lib/components/divider/__tests__/HtmlDivider.test.d.ts

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

package/lib/components/divider/__tests__/HtmlDivider.test.js

@@ -0,0 +1,144 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { createTheme } from "../../../theme/createTheme.js";
+import { ThemeProvider } from "../../../theme/ThemeProvider.js";
+import { generateHtmlDividerStyles, HtmlDivider } from "../HtmlDivider.js";
+function renderHtmlDivider(element) {
+    return renderToStaticMarkup(element);
+}
+describe("HtmlDivider", () => {
+    it("renders default theme styles across modern, Outlook, and legacy clients", () => {
+        const theme = createTheme();
+        const html = renderHtmlDivider(_jsx(ThemeProvider, { theme: theme, children: _jsx(HtmlDivider, {}) }));
+        // Modern clients: inline height and background color.
+        expect(html).toContain("height:4px");
+        expect(html).toContain("background-color:#000000");
+        // Outlook: mso-line-height-rule with matching line-height; font-size:0 keeps the spacer character from adding height.
+        expect(html).toContain("mso-line-height-rule:exactly");
+        expect(html).toContain("line-height:4px");
+        expect(html).toContain("font-size:0");
+        // Legacy Outlook: attribute fallbacks for clients that ignore inline CSS.
+        expect(html).toContain('bgcolor="#000000"');
+        expect(html).toContain('height="4"');
+    });
+    it("applies variant styles over base theme styles", () => {
+        const theme = createTheme({
+            divider: {
+                variants: {
+                    thick: { height: 10, backgroundColor: "#222222" },
+                },
+            },
+        });
+        const html = renderHtmlDivider(_jsx(ThemeProvider, { theme: theme, children: _jsx(HtmlDivider, { variant: "thick" }) }));
+        expect(html).toContain("height:10px");
+        expect(html).toContain("background-color:#222222");
+        expect(html).toContain("htmlDivider--thick");
+    });
+    it("inherits base divider styles not overridden by variant", () => {
+        const theme = createTheme({
+            divider: {
+                backgroundColor: "#222222",
+                variants: {
+                    thick: { height: 10 },
+                },
+            },
+        });
+        const html = renderHtmlDivider(_jsx(ThemeProvider, { theme: theme, children: _jsx(HtmlDivider, { variant: "thick" }) }));
+        expect(html).toContain("height:10px");
+        expect(html).toContain("background-color:#222222");
+    });
+    it("applies defaultVariant when no variant prop is specified", () => {
+        const theme = createTheme({
+            divider: {
+                defaultVariant: "thin",
+                variants: {
+                    thin: { height: 1 },
+                },
+            },
+        });
+        const html = renderHtmlDivider(_jsx(ThemeProvider, { theme: theme, children: _jsx(HtmlDivider, {}) }));
+        expect(html).toContain("height:1px");
+        expect(html).toContain("htmlDivider--thin");
+    });
+    it("per-instance height prop overrides theme and variant", () => {
+        const theme = createTheme({
+            divider: {
+                height: 4,
+                variants: { thin: { height: 1 } },
+            },
+        });
+        const html = renderHtmlDivider(_jsx(ThemeProvider, { theme: theme, children: _jsx(HtmlDivider, { variant: "thin", height: 12 }) }));
+        expect(html).toContain("height:12px");
+    });
+    it("applies variant backgroundImage with the variant backgroundColor as fallback", () => {
+        const theme = createTheme({
+            divider: {
+                variants: {
+                    gradient: {
+                        backgroundColor: "#5B4FC7",
+                        backgroundImage: "linear-gradient(to right, red, blue)",
+                    },
+                },
+            },
+        });
+        const html = renderHtmlDivider(_jsx(ThemeProvider, { theme: theme, children: _jsx(HtmlDivider, { variant: "gradient" }) }));
+        expect(html).toContain("background-color:#5B4FC7");
+        expect(html).toContain("background-image:linear-gradient(to right, red, blue)");
+    });
+    it("lets consumer style prop layer over theme styles", () => {
+        const theme = createTheme();
+        const html = renderHtmlDivider(_jsx(ThemeProvider, { theme: theme, children: _jsx(HtmlDivider, { style: { backgroundImage: "linear-gradient(to right, red, blue)" } }) }));
+        // Solid color fallback stays for clients that don't render gradients.
+        expect(html).toContain("background-color:#000000");
+        expect(html).toContain("background-image:linear-gradient(to right, red, blue)");
+    });
+    it("falls back to default styles when used without a ThemeProvider", () => {
+        const html = renderHtmlDivider(_jsx(HtmlDivider, {}));
+        expect(html).toContain("height:4px");
+        expect(html).toContain("background-color:#000000");
+    });
+    it("throws when variant is set without a ThemeProvider", () => {
+        expect(() => renderHtmlDivider(_jsx(HtmlDivider, { variant: "thin" }))).toThrow();
+    });
+});
+describe("generateHtmlDividerStyles", () => {
+    it("returns empty CSS when no variants are defined", () => {
+        const theme = createTheme();
+        expect(generateHtmlDividerStyles(theme)).toBe("");
+    });
+    it("emits height and line-height together for responsive variants", () => {
+        const theme = createTheme({
+            divider: {
+                variants: {
+                    thin: { height: { default: 4, mobile: 2 } },
+                },
+            },
+        });
+        const result = generateHtmlDividerStyles(theme);
+        expect(result).toContain(".htmlDivider--thin td");
+        expect(result).toContain("height: 2px !important");
+        expect(result).toContain("line-height: 2px !important");
+    });
+    it("emits background-color overrides for responsive variants", () => {
+        const theme = createTheme({
+            divider: {
+                variants: {
+                    accent: { backgroundColor: { default: "#5B4FC7", mobile: "#FF6B6B" } },
+                },
+            },
+        });
+        const result = generateHtmlDividerStyles(theme);
+        expect(result).toContain("background-color: #FF6B6B !important");
+    });
+    it("emits no media queries for a non-responsive variant", () => {
+        const theme = createTheme({
+            divider: {
+                variants: {
+                    thick: { height: 8 },
+                },
+            },
+        });
+        expect(generateHtmlDividerStyles(theme)).not.toContain("@media");
+    });
+});

package/lib/components/divider/__tests__/MjmlDivider.test.d.ts

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

package/lib/components/divider/__tests__/MjmlDivider.test.js

@@ -0,0 +1,43 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MjmlColumn } from "@faire/mjml-react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { renderMailHtml } from "../../../server/renderMailHtml.js";
+import { createTheme } from "../../../theme/createTheme.js";
+import { MjmlMailRoot } from "../../mailRoot/MjmlMailRoot.js";
+import { MjmlSection } from "../../section/MjmlSection.js";
+import { MjmlDivider } from "../MjmlDivider.js";
+describe("MjmlDivider integration", () => {
+    it("produces no MJML warnings inside an MjmlMailRoot", () => {
+        const theme = createTheme({
+            divider: {
+                variants: {
+                    thin: { height: 1, backgroundColor: "#999999" },
+                    thick: { height: 8, backgroundColor: "#222222" },
+                },
+            },
+        });
+        const { mjmlWarnings } = renderMailHtml(_jsx(MjmlMailRoot, { theme: theme, children: _jsx(MjmlSection, { children: _jsxs(MjmlColumn, { children: [_jsx(MjmlDivider, {}), _jsx(MjmlDivider, { variant: "thin" }), _jsx(MjmlDivider, { variant: "thick" })] }) }) }));
+        expect(mjmlWarnings).toEqual([]);
+    });
+    it("applies a variant modifier class to both mjmlDivider and htmlDivider blocks", () => {
+        const theme = createTheme({
+            divider: {
+                variants: {
+                    thick: { height: 8 },
+                },
+            },
+        });
+        const { html } = renderMailHtml(_jsx(MjmlMailRoot, { theme: theme, children: _jsx(MjmlSection, { children: _jsx(MjmlColumn, { children: _jsx(MjmlDivider, { variant: "thick" }) }) }) }));
+        expect(html).toContain("mjmlDivider--thick");
+        expect(html).toContain("htmlDivider--thick");
+    });
+    it("falls back to default theme values when used without a ThemeProvider", () => {
+        const html = renderToStaticMarkup(_jsx(MjmlDivider, {}));
+        expect(html).toContain("height:4px");
+        expect(html).toContain("background-color:#000000");
+    });
+    it("throws when variant is set without a ThemeProvider", () => {
+        expect(() => renderToStaticMarkup(_jsx(MjmlDivider, { variant: "thin" }))).toThrow();
+    });
+});

package/lib/components/divider/defaultDividerStyles.d.ts

@@ -0,0 +1,2 @@
+import type { DividerStyles } from "../../theme/themeTypes.js";
+export declare const defaultDividerStyles: DividerStyles;

package/lib/components/divider/defaultDividerStyles.js

@@ -0,0 +1,4 @@
+export const defaultDividerStyles = {
+    height: 4,
+    backgroundColor: "#000000",
+};

package/lib/components/divider/dividerProps.d.ts

@@ -0,0 +1,38 @@
+import type { CSSProperties } from "react";
+import type { DividerVariantName } from "../../theme/themeTypes.js";
+export interface DividerProps {
+    /**
+     * The component's variant to apply, as defined in the theme.
+     *
+     * Custom variants should be defined in the theme through module augmentation:
+     *
+     * ```ts
+     * declare module "@comet/mail-react" {
+     *     interface DividerVariants { thin: true; thick: true }
+     * }
+     * ```
+     *
+     * ```ts
+     * const theme = createTheme({
+     *     divider: {
+     *         variants: {
+     *             thin: { height: 1 },
+     *             thick: { height: 8 },
+     *         },
+     *     },
+     * });
+     * ```
+     */
+    variant?: DividerVariantName;
+    /** Height of the divider in pixels. */
+    height?: number;
+    /** Background color of the divider (e.g. `"#FF0000"`). */
+    backgroundColor?: string;
+    /**
+     * Background image for the divider — typically a gradient. Clients that
+     * don't render `background-image` fall back to the solid `backgroundColor`.
+     */
+    backgroundImage?: string;
+    className?: string;
+    style?: CSSProperties;
+}

package/lib/components/divider/dividerProps.js

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

package/lib/components/divider/generateResponsiveDividerCss.d.ts

@@ -0,0 +1,8 @@
+import type { Theme } from "../../theme/themeTypes.js";
+interface GenerateResponsiveDividerCssOptions {
+    /** Selector for divider style overrides, given a variant name. */
+    styleSelector: (variantName: string) => string;
+}
+/** Generates responsive CSS media queries for divider variant overrides. */
+export declare function generateResponsiveDividerCss(theme: Theme, options: GenerateResponsiveDividerCssOptions): string;
+export {};

package/lib/components/divider/generateResponsiveDividerCss.js

@@ -0,0 +1,55 @@
+import { getResponsiveOverrides } from "../../theme/responsiveValue.js";
+import { css } from "../../utils/css.js";
+const colorCssProperties = [
+    ["backgroundColor", "background-color"],
+    ["backgroundImage", "background-image"],
+];
+/** Generates responsive CSS media queries for divider variant overrides. */
+export function generateResponsiveDividerCss(theme, options) {
+    const { variants } = theme.divider;
+    if (!variants) {
+        return css ``;
+    }
+    const cssChunks = [];
+    for (const [variantName, variantStyles] of Object.entries(variants)) {
+        if (!variantStyles) {
+            continue;
+        }
+        const overrides = new Map();
+        const heightValue = variantStyles.height;
+        if (heightValue !== undefined) {
+            for (const { breakpointKey, value: breakpointValue } of getResponsiveOverrides(heightValue)) {
+                const declarations = overrides.get(breakpointKey) ?? [];
+                // line-height matches height so Outlook honors the declared cell height.
+                declarations.push(`height: ${breakpointValue}px !important`);
+                declarations.push(`line-height: ${breakpointValue}px !important`);
+                overrides.set(breakpointKey, declarations);
+            }
+        }
+        for (const [themeKey, cssProperty] of colorCssProperties) {
+            const value = variantStyles[themeKey];
+            if (value === undefined) {
+                continue;
+            }
+            for (const { breakpointKey, value: breakpointValue } of getResponsiveOverrides(value)) {
+                const declarations = overrides.get(breakpointKey) ?? [];
+                declarations.push(`${cssProperty}: ${breakpointValue} !important`);
+                overrides.set(breakpointKey, declarations);
+            }
+        }
+        for (const [breakpointKey, declarations] of overrides) {
+            const breakpoint = theme.breakpoints[breakpointKey];
+            if (!breakpoint) {
+                continue;
+            }
+            cssChunks.push(css `
+                ${breakpoint.belowMediaQuery} {
+                    ${options.styleSelector(variantName)} {
+                        ${declarations.join(";\n")}
+                    }
+                }
+            `);
+        }
+    }
+    return cssChunks.join("\n");
+}

package/lib/components/image/HtmlImage.d.ts

@@ -0,0 +1,11 @@
+import type { ComponentProps, ReactNode } from "react";
+export type HtmlImageProps = ComponentProps<"img">;
+/**
+ * Renders an `<img>` tag that adapts to its container width below the default
+ * breakpoint.
+ *
+ * Use within raw HTML context — HTML-only emails or
+ * [MJML ending tags](https://documentation.mjml.io/#ending-tags) like `MjmlRaw`.
+ * For MJML context, use `MjmlImage`.
+ */
+export declare function HtmlImage({ className, ...restProps }: HtmlImageProps): ReactNode;

package/lib/components/image/HtmlImage.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import clsx from "clsx";
+import { registerStyles } from "../../styles/registerStyles.js";
+import { css } from "../../utils/css.js";
+/**
+ * Renders an `<img>` tag that adapts to its container width below the default
+ * breakpoint.
+ *
+ * Use within raw HTML context — HTML-only emails or
+ * [MJML ending tags](https://documentation.mjml.io/#ending-tags) like `MjmlRaw`.
+ * For MJML context, use `MjmlImage`.
+ */
+export function HtmlImage({ className, ...restProps }) {
+    return _jsx("img", { className: clsx("htmlImage", className), ...restProps });
+}
+registerStyles((theme) => css `
+        ${theme.breakpoints.default.belowMediaQuery} {
+            .htmlImage {
+                width: 100%;
+                height: auto;
+            }
+        }
+    `);