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

package/lib/index.d.ts

@@ -4,7 +4,23 @@ export { OneOfBlock } from "./blocks/factories/OneOfBlock.js";
 export { OptionalBlock } from "./blocks/factories/OptionalBlock.js";
 export type { SupportedBlocks } from "./blocks/factories/types.js";
 export type { PropsWithData } from "./blocks/helpers/PropsWithData.js";
+export type { HtmlInlineLinkProps } from "./components/inlineLink/HtmlInlineLink.js";
+export { HtmlInlineLink } from "./components/inlineLink/HtmlInlineLink.js";
+export { MjmlMailRoot } from "./components/mailRoot/MjmlMailRoot.js";
+export type { MjmlSectionProps } from "./components/section/MjmlSection.js";
+export { MjmlSection } from "./components/section/MjmlSection.js";
+export type { HtmlTextProps } from "./components/text/HtmlText.js";
+export { HtmlText } from "./components/text/HtmlText.js";
+export type { MjmlTextProps } from "./components/text/MjmlText.js";
+export { MjmlText } from "./components/text/MjmlText.js";
+export { registerStyles } from "./styles/registerStyles.js";
+export { createBreakpoint } from "./theme/createBreakpoint.js";
+export { createTheme } from "./theme/createTheme.js";
+export type { ResponsiveValue } from "./theme/responsiveValue.js";
+export { getDefaultFromResponsiveValue, getResponsiveOverrides } from "./theme/responsiveValue.js";
+export { ThemeProvider, useTheme } from "./theme/ThemeProvider.js";
+export type { TextStyles, TextVariants, TextVariantStyles, Theme, ThemeBackgroundColors, ThemeBreakpoint, ThemeBreakpoints, ThemeColors, ThemeSizes, ThemeText, } from "./theme/themeTypes.js";
 export { css } from "./utils/css.js";
-export { Mjml, MjmlAccordion, MjmlAccordionElement, type IMjmlAccordionElementProps as MjmlAccordionElementProps, type IMjmlAccordionProps as MjmlAccordionProps, MjmlAccordionText, type IMjmlAccordionTextProps as MjmlAccordionTextProps, MjmlAccordionTitle, type IMjmlAccordionTitleProps as MjmlAccordionTitleProps, MjmlAll, type IMjmlAllProps as MjmlAllProps, MjmlAttributes, type IMjmlAttributesProps as MjmlAttributesProps, MjmlBody, type IMjmlBodyProps as MjmlBodyProps, MjmlBreakpoint, type IMjmlBreakpointProps as MjmlBreakpointProps, MjmlButton, type IMjmlButtonProps as MjmlButtonProps, MjmlCarousel, MjmlCarouselImage, type IMjmlCarouselImageProps as MjmlCarouselImageProps, type IMjmlCarouselProps as MjmlCarouselProps, MjmlClass, type IMjmlClassProps as MjmlClassProps, MjmlColumn, type IMjmlColumnProps as MjmlColumnProps, MjmlDivider, type IMjmlDividerProps as MjmlDividerProps, MjmlFont, type IMjmlFontProps as MjmlFontProps, MjmlGroup, type IMjmlGroupProps as MjmlGroupProps, MjmlHead, type IMjmlHeadProps as MjmlHeadProps, MjmlHero, type IMjmlHeroProps as MjmlHeroProps, MjmlHtmlAttribute, type IMjmlHtmlAttributeProps as MjmlHtmlAttributeProps, MjmlHtmlAttributes, type IMjmlHtmlAttributesProps as MjmlHtmlAttributesProps, MjmlImage, type IMjmlImageProps as MjmlImageProps, MjmlInclude, type IMjmlIncludeProps as MjmlIncludeProps, MjmlNavbar, MjmlNavbarLink, type IMjmlNavbarLinkProps as MjmlNavbarLinkProps, type IMjmlNavbarProps as MjmlNavbarProps, MjmlPreview, type IMjmlPreviewProps as MjmlPreviewProps, type IMjmlProps as MjmlProps, MjmlRaw, type IMjmlRawProps as MjmlRawProps, MjmlSection, type IMjmlSectionProps as MjmlSectionProps, MjmlSelector, type IMjmlSelectorProps as MjmlSelectorProps, MjmlSocial, MjmlSocialElement, type IMjmlSocialElementProps as MjmlSocialElementProps, type IMjmlSocialProps as MjmlSocialProps, MjmlSpacer, type IMjmlSpacerProps as MjmlSpacerProps, MjmlStyle, type IMjmlStyleProps as MjmlStyleProps, MjmlTable, type IMjmlTableProps as MjmlTableProps, MjmlText, type IMjmlTextProps as MjmlTextProps, MjmlTitle, type IMjmlTitleProps as MjmlTitleProps, MjmlWrapper, type IMjmlWrapperProps as MjmlWrapperProps, } from "@faire/mjml-react";
+export { Mjml, MjmlAccordion, MjmlAccordionElement, type IMjmlAccordionElementProps as MjmlAccordionElementProps, type IMjmlAccordionProps as MjmlAccordionProps, MjmlAccordionText, type IMjmlAccordionTextProps as MjmlAccordionTextProps, MjmlAccordionTitle, type IMjmlAccordionTitleProps as MjmlAccordionTitleProps, MjmlAll, type IMjmlAllProps as MjmlAllProps, MjmlAttributes, type IMjmlAttributesProps as MjmlAttributesProps, MjmlBody, type IMjmlBodyProps as MjmlBodyProps, MjmlBreakpoint, type IMjmlBreakpointProps as MjmlBreakpointProps, MjmlButton, type IMjmlButtonProps as MjmlButtonProps, MjmlCarousel, MjmlCarouselImage, type IMjmlCarouselImageProps as MjmlCarouselImageProps, type IMjmlCarouselProps as MjmlCarouselProps, MjmlClass, type IMjmlClassProps as MjmlClassProps, MjmlColumn, type IMjmlColumnProps as MjmlColumnProps, MjmlDivider, type IMjmlDividerProps as MjmlDividerProps, MjmlFont, type IMjmlFontProps as MjmlFontProps, MjmlGroup, type IMjmlGroupProps as MjmlGroupProps, MjmlHead, type IMjmlHeadProps as MjmlHeadProps, MjmlHero, type IMjmlHeroProps as MjmlHeroProps, MjmlHtmlAttribute, type IMjmlHtmlAttributeProps as MjmlHtmlAttributeProps, MjmlHtmlAttributes, type IMjmlHtmlAttributesProps as MjmlHtmlAttributesProps, MjmlImage, type IMjmlImageProps as MjmlImageProps, MjmlInclude, type IMjmlIncludeProps as MjmlIncludeProps, MjmlNavbar, MjmlNavbarLink, type IMjmlNavbarLinkProps as MjmlNavbarLinkProps, type IMjmlNavbarProps as MjmlNavbarProps, MjmlPreview, type IMjmlPreviewProps as MjmlPreviewProps, type IMjmlProps as MjmlProps, MjmlRaw, type IMjmlRawProps as MjmlRawProps, MjmlSelector, type IMjmlSelectorProps as MjmlSelectorProps, MjmlSocial, MjmlSocialElement, type IMjmlSocialElementProps as MjmlSocialElementProps, type IMjmlSocialProps as MjmlSocialProps, MjmlSpacer, type IMjmlSpacerProps as MjmlSpacerProps, MjmlStyle, type IMjmlStyleProps as MjmlStyleProps, MjmlTable, type IMjmlTableProps as MjmlTableProps, MjmlTitle, type IMjmlTitleProps as MjmlTitleProps, MjmlWrapper, type IMjmlWrapperProps as MjmlWrapperProps, } from "@faire/mjml-react";
 export { MjmlComment, MjmlConditionalComment, MjmlHtml, MjmlTrackingPixel, MjmlYahooStyle } from "@faire/mjml-react/extensions/index.js";
 export { renderToMjml } from "@faire/mjml-react/utils/renderToMjml.js";

package/lib/index.js

@@ -2,7 +2,17 @@ export { BlocksBlock } from "./blocks/factories/BlocksBlock.js";
 export { ListBlock } from "./blocks/factories/ListBlock.js";
 export { OneOfBlock } from "./blocks/factories/OneOfBlock.js";
 export { OptionalBlock } from "./blocks/factories/OptionalBlock.js";
+export { HtmlInlineLink } from "./components/inlineLink/HtmlInlineLink.js";
+export { MjmlMailRoot } from "./components/mailRoot/MjmlMailRoot.js";
+export { MjmlSection } from "./components/section/MjmlSection.js";
+export { HtmlText } from "./components/text/HtmlText.js";
+export { MjmlText } from "./components/text/MjmlText.js";
+export { registerStyles } from "./styles/registerStyles.js";
+export { createBreakpoint } from "./theme/createBreakpoint.js";
+export { createTheme } from "./theme/createTheme.js";
+export { getDefaultFromResponsiveValue, getResponsiveOverrides } from "./theme/responsiveValue.js";
+export { ThemeProvider, useTheme } from "./theme/ThemeProvider.js";
 export { css } from "./utils/css.js";
-export { Mjml, MjmlAccordion, MjmlAccordionElement, MjmlAccordionText, MjmlAccordionTitle, MjmlAll, MjmlAttributes, MjmlBody, MjmlBreakpoint, MjmlButton, MjmlCarousel, MjmlCarouselImage, MjmlClass, MjmlColumn, MjmlDivider, MjmlFont, MjmlGroup, MjmlHead, MjmlHero, MjmlHtmlAttribute, MjmlHtmlAttributes, MjmlImage, MjmlInclude, MjmlNavbar, MjmlNavbarLink, MjmlPreview, MjmlRaw, MjmlSection, MjmlSelector, MjmlSocial, MjmlSocialElement, MjmlSpacer, MjmlStyle, MjmlTable, MjmlText, MjmlTitle, MjmlWrapper, } from "@faire/mjml-react";
+export { Mjml, MjmlAccordion, MjmlAccordionElement, MjmlAccordionText, MjmlAccordionTitle, MjmlAll, MjmlAttributes, MjmlBody, MjmlBreakpoint, MjmlButton, MjmlCarousel, MjmlCarouselImage, MjmlClass, MjmlColumn, MjmlDivider, MjmlFont, MjmlGroup, MjmlHead, MjmlHero, MjmlHtmlAttribute, MjmlHtmlAttributes, MjmlImage, MjmlInclude, MjmlNavbar, MjmlNavbarLink, MjmlPreview, MjmlRaw, MjmlSelector, MjmlSocial, MjmlSocialElement, MjmlSpacer, MjmlStyle, MjmlTable, MjmlTitle, MjmlWrapper, } from "@faire/mjml-react";
 export { MjmlComment, MjmlConditionalComment, MjmlHtml, MjmlTrackingPixel, MjmlYahooStyle } from "@faire/mjml-react/extensions/index.js";
 export { renderToMjml } from "@faire/mjml-react/utils/renderToMjml.js";

package/lib/server/index.d.ts

@@ -0,0 +1 @@
+export { renderMailHtml } from "./renderMailHtml.js";

package/lib/server/index.js

@@ -0,0 +1 @@
+export { renderMailHtml } from "./renderMailHtml.js";

package/lib/server/renderMailHtml.d.ts

@@ -0,0 +1,9 @@
+import mjml2html from "mjml";
+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): {
+    html: string;
+    mjmlWarnings: MjmlWarning[];
+};
+export {};

package/lib/server/renderMailHtml.js

@@ -0,0 +1,7 @@
+import { renderToMjml } from "@faire/mjml-react/utils/renderToMjml.js";
+import mjml2html from "mjml";
+export function renderMailHtml(element, options) {
+    const mjmlString = renderToMjml(element);
+    const { html, errors: mjmlWarnings } = mjml2html(mjmlString, { validationLevel: "soft", ...options });
+    return { html, mjmlWarnings };
+}

package/lib/server/renderMailHtml.test.d.ts

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

package/lib/server/renderMailHtml.test.js

@@ -0,0 +1,43 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { MjmlColumn, MjmlText } from "@faire/mjml-react";
+import { describe, expect, it } from "vitest";
+import { MjmlMailRoot } from "../components/mailRoot/MjmlMailRoot.js";
+import { MjmlSection } from "../components/section/MjmlSection.js";
+import { registerStyles } from "../styles/registerStyles.js";
+import { css } from "../utils/css.js";
+import { renderMailHtml } from "./renderMailHtml.js";
+describe("server/renderMailHtml", () => {
+    it("produces HTML with a doctype", () => {
+        const { html } = renderMailHtml(_jsx(MjmlMailRoot, { children: _jsx(MjmlSection, { children: _jsx(MjmlColumn, { children: _jsx(MjmlText, { children: "Hello" }) }) }) }));
+        expect(html.toLowerCase()).toMatch(/^<!doctype html>/);
+    });
+    it("includes the passed-in text content", () => {
+        const textContent = "Welcome to @comet/mail-react";
+        const { html } = renderMailHtml(_jsx(MjmlMailRoot, { children: _jsx(MjmlSection, { children: _jsx(MjmlColumn, { children: _jsx(MjmlText, { children: textContent }) }) }) }));
+        expect(html).toContain(textContent);
+    });
+    it("includes registered styles in the rendered HTML", () => {
+        registerStyles(css `
+            .myComponent {
+                color: red;
+            }
+        `);
+        const { html } = renderMailHtml(_jsx(MjmlMailRoot, { children: _jsx(MjmlSection, { children: _jsx(MjmlColumn, { children: _jsx(MjmlText, { children: "Hello" }) }) }) }));
+        expect(html).toContain(".myComponent");
+        expect(html).toContain("color: red");
+    });
+    it("includes function-style registered styles resolved with the theme", () => {
+        registerStyles((theme) => css `
+                .themed {
+                    width: ${theme.sizes.bodyWidth}px;
+                }
+            `);
+        const { html } = renderMailHtml(_jsx(MjmlMailRoot, { children: _jsx(MjmlSection, { children: _jsx(MjmlColumn, { children: _jsx(MjmlText, { children: "Hello" }) }) }) }));
+        expect(html).toContain(".themed");
+        expect(html).toContain("width: 600px");
+    });
+    it("produces no MJML warnings for a valid component tree", () => {
+        const { mjmlWarnings } = renderMailHtml(_jsx(MjmlMailRoot, { children: _jsx(MjmlSection, { children: _jsx(MjmlColumn, { children: _jsx(MjmlText, { children: "No warnings expected" }) }) }) }));
+        expect(mjmlWarnings).toEqual([]);
+    });
+});

package/lib/storybook/CopyMailHtmlButton.d.ts

@@ -0,0 +1,4 @@
+/** @jsxRuntime classic */
+/** @jsx React.createElement */
+import React from "react";
+export declare function CopyMailHtmlButton(): React.JSX.Element;

package/lib/storybook/CopyMailHtmlButton.js

@@ -0,0 +1,33 @@
+/** @jsxRuntime classic */
+/** @jsx React.createElement */
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { Button } from "storybook/internal/components";
+import { useChannel } from "storybook/manager-api";
+const RENDER_RESULT_EVENT = "comet-mail-render-result";
+export function CopyMailHtmlButton() {
+    const htmlRef = useRef("");
+    const [copied, setCopied] = useState(false);
+    const copiedTimeoutRef = useRef(undefined);
+    useChannel({
+        [RENDER_RESULT_EVENT]: ({ html }) => {
+            htmlRef.current = html;
+            setCopied(false);
+        },
+    });
+    useEffect(() => {
+        return () => {
+            if (copiedTimeoutRef.current) {
+                clearTimeout(copiedTimeoutRef.current);
+            }
+        };
+    }, []);
+    const handleClick = useCallback(async () => {
+        await navigator.clipboard.writeText(htmlRef.current);
+        setCopied(true);
+        if (copiedTimeoutRef.current) {
+            clearTimeout(copiedTimeoutRef.current);
+        }
+        copiedTimeoutRef.current = setTimeout(() => setCopied(false), 2000);
+    }, []);
+    return (React.createElement(Button, { size: "small", onClick: handleClick }, copied ? "Copied to clipboard!" : "Copy Mail HTML"));
+}

package/lib/storybook/MailRendererDecorator.d.ts

@@ -0,0 +1,7 @@
+import type { Theme } from "../theme/themeTypes.js";
+export declare function MailRendererDecorator(Story: () => React.JSX.Element, context: {
+    parameters: {
+        mailRoot?: boolean;
+        theme?: Theme;
+    };
+}): import("react/jsx-runtime").JSX.Element;

package/lib/storybook/MailRendererDecorator.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useChannel, useGlobals } from "storybook/preview-api";
+import { renderMailHtml } from "../client/renderMailHtml.js";
+import { MjmlMailRoot } from "../components/mailRoot/MjmlMailRoot.js";
+import { replaceImagesWithPublicUrl } from "./replaceImagesWithPublicUrl.js";
+const RENDER_RESULT_EVENT = "comet-mail-render-result";
+export function MailRendererDecorator(Story, context) {
+    const [globals] = useGlobals();
+    const emit = useChannel({});
+    const { html: rawHtml, mjmlWarnings } = renderMailHtml(context.parameters.mailRoot === false ? (_jsx(Story, {})) : (_jsx(MjmlMailRoot, { theme: context.parameters.theme, children: _jsx(Story, {}) })));
+    for (const warning of mjmlWarnings) {
+        console.warn("MJML warning:", warning);
+    }
+    const html = globals.usePublicImageUrls ? replaceImagesWithPublicUrl(rawHtml) : rawHtml;
+    emit(RENDER_RESULT_EVENT, { html, mjmlWarnings });
+    return _jsx("div", { dangerouslySetInnerHTML: { __html: html } });
+}

package/lib/storybook/MjmlWarningsPanel.d.ts

@@ -0,0 +1,7 @@
+/** @jsxRuntime classic */
+/** @jsx React.createElement */
+import React from "react";
+export declare function MjmlWarningsPanel({ active }: {
+    active: boolean;
+}): React.JSX.Element;
+export declare function MjmlWarningsPanelTitle(): React.JSX.Element;

package/lib/storybook/MjmlWarningsPanel.js

@@ -0,0 +1,33 @@
+/** @jsxRuntime classic */
+/** @jsx React.createElement */
+import React, { useState } from "react";
+import { AddonPanel, Badge } from "storybook/internal/components";
+import { useChannel } from "storybook/manager-api";
+const RENDER_RESULT_EVENT = "comet-mail-render-result";
+export function MjmlWarningsPanel({ active }) {
+    const [renderResult, setRenderResult] = useState(null);
+    useChannel({
+        [RENDER_RESULT_EVENT]: (result) => {
+            setRenderResult(result);
+        },
+    });
+    return (React.createElement(AddonPanel, { active: active }, renderResult && (React.createElement("div", { style: { padding: 16 } }, renderResult.mjmlWarnings.length === 0 ? (React.createElement("p", { style: { color: "green" } }, "\u2713 No MJML warnings")) : (React.createElement("ul", { style: { margin: 0, padding: 0, listStyle: "none" } }, renderResult.mjmlWarnings.map((warning, index) => (React.createElement("li", { key: index, style: { marginBottom: 8 } },
+        React.createElement("strong", null, warning.tagName),
+        " (line ",
+        warning.line,
+        "): ",
+        warning.message)))))))));
+}
+export function MjmlWarningsPanelTitle() {
+    const [renderResult, setRenderResult] = useState(null);
+    useChannel({
+        [RENDER_RESULT_EVENT]: (result) => {
+            setRenderResult(result);
+        },
+    });
+    const warningCount = renderResult?.mjmlWarnings.length ?? 0;
+    const hasWarnings = warningCount > 0;
+    return (React.createElement("div", { style: { display: "flex", alignItems: "center", gap: 6 } },
+        React.createElement("span", null, "MJML Warnings"),
+        React.createElement(Badge, { compact: true, status: hasWarnings ? "negative" : "positive" }, hasWarnings ? warningCount : "✓")));
+}

package/lib/storybook/UsePublicImageUrlsToggle.d.ts

@@ -0,0 +1,4 @@
+/** @jsxRuntime classic */
+/** @jsx React.createElement */
+import React from "react";
+export declare function UsePublicImageUrlsToggle(): React.JSX.Element;

package/lib/storybook/UsePublicImageUrlsToggle.js

@@ -0,0 +1,14 @@
+/** @jsxRuntime classic */
+/** @jsx React.createElement */
+import React from "react";
+import { IconButton, TooltipNote, WithTooltip } from "storybook/internal/components";
+import { useGlobals } from "storybook/manager-api";
+export function UsePublicImageUrlsToggle() {
+    const [globals, updateGlobals] = useGlobals();
+    const isActive = Boolean(globals.usePublicImageUrls);
+    return (React.createElement(WithTooltip, { tooltip: React.createElement(TooltipNote, { note: "Helpful to test with real images on external devices that cannot access localhost, e.g. Email on Acid." }), trigger: "hover" },
+        React.createElement(IconButton, { size: "small", active: isActive, onClick: () => updateGlobals({ usePublicImageUrls: !isActive }) },
+            React.createElement("input", { type: "checkbox", checked: isActive, readOnly: true, style: { pointerEvents: "none", marginLeft: 4 } }),
+            "Use public image URLs",
+            React.createElement("span", { role: "img", "aria-label": "info" }, "\u2139\uFE0F"))));
+}

package/lib/storybook/index.d.ts

@@ -0,0 +1,2 @@
+export declare function managerEntries(existing?: string[]): string[];
+export declare function previewAnnotations(input?: string[]): string[];

package/lib/storybook/index.js

@@ -0,0 +1,9 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const directoryOfThisFile = dirname(fileURLToPath(import.meta.url));
+export function managerEntries(existing = []) {
+    return [...existing, resolve(directoryOfThisFile, "manager.js")];
+}
+export function previewAnnotations(input = []) {
+    return [...input, resolve(directoryOfThisFile, "preview.js")];
+}

package/lib/storybook/manager.d.ts

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

package/lib/storybook/manager.js

@@ -0,0 +1,25 @@
+/** @jsxRuntime classic */
+/** @jsx React.createElement */
+import React from "react";
+import { addons, types } from "storybook/manager-api";
+import { CopyMailHtmlButton } from "./CopyMailHtmlButton.js";
+import { MjmlWarningsPanel, MjmlWarningsPanelTitle } from "./MjmlWarningsPanel.js";
+import { UsePublicImageUrlsToggle } from "./UsePublicImageUrlsToggle.js";
+const ADDON_ID = "comet-mail-react";
+addons.register(ADDON_ID, () => {
+    addons.add(`${ADDON_ID}/copy-html`, {
+        type: types.TOOL,
+        title: "Copy Mail HTML",
+        render: () => React.createElement(CopyMailHtmlButton, null),
+    });
+    addons.add(`${ADDON_ID}/public-urls`, {
+        type: types.TOOL,
+        title: "Use public image URLs",
+        render: () => React.createElement(UsePublicImageUrlsToggle, null),
+    });
+    addons.add(`${ADDON_ID}/mjml-warnings`, {
+        type: types.PANEL,
+        title: () => React.createElement(MjmlWarningsPanelTitle, null),
+        render: ({ active }) => React.createElement(MjmlWarningsPanel, { active: Boolean(active) }),
+    });
+});

package/lib/storybook/preview.d.ts

@@ -0,0 +1,5 @@
+import { MailRendererDecorator } from "./MailRendererDecorator.js";
+export declare const decorators: (typeof MailRendererDecorator)[];
+export declare const initialGlobals: {
+    usePublicImageUrls: boolean;
+};

package/lib/storybook/preview.js

@@ -0,0 +1,5 @@
+import { MailRendererDecorator } from "./MailRendererDecorator.js";
+export const decorators = [MailRendererDecorator];
+export const initialGlobals = {
+    usePublicImageUrls: false,
+};

package/lib/storybook/replaceImagesWithPublicUrl.d.ts

@@ -0,0 +1 @@
+export declare function replaceImagesWithPublicUrl(html: string): string;

package/lib/storybook/replaceImagesWithPublicUrl.js

@@ -0,0 +1,15 @@
+export function replaceImagesWithPublicUrl(html) {
+    let seedCounter = 0;
+    return html.replace(/<img\b[^>]*>/gi, (imgTag) => {
+        const widthMatch = imgTag.match(/\bwidth="(\d+)"/);
+        const heightMatch = imgTag.match(/\bheight="(\d+)"/);
+        if (!widthMatch || !heightMatch) {
+            return imgTag;
+        }
+        const retinaWidth = parseInt(widthMatch[1], 10) * 2;
+        const retinaHeight = parseInt(heightMatch[1], 10) * 2;
+        const seed = seedCounter++;
+        const publicUrl = `https://picsum.photos/seed/${seed}/${retinaWidth}/${retinaHeight}`;
+        return imgTag.replace(/\bsrc="[^"]*"/, `src="${publicUrl}"`);
+    });
+}

package/lib/storybook/replaceImagesWithPublicUrl.test.d.ts

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

package/lib/storybook/replaceImagesWithPublicUrl.test.js

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import { replaceImagesWithPublicUrl } from "./replaceImagesWithPublicUrl.js";
+describe("replaceImagesWithPublicUrl", () => {
+    it("replaces src with picsum URL using doubled dimensions", () => {
+        const html = '<img src="original.jpg" width="300" height="200" />';
+        const result = replaceImagesWithPublicUrl(html);
+        expect(result).toBe('<img src="https://picsum.photos/seed/0/600/400" width="300" height="200" />');
+    });
+    it("handles height before width", () => {
+        const html = '<img src="original.jpg" height="200" width="300" />';
+        const result = replaceImagesWithPublicUrl(html);
+        expect(result).toBe('<img src="https://picsum.photos/seed/0/600/400" height="200" width="300" />');
+    });
+    it("handles attributes before width and height", () => {
+        const html = '<img alt="photo" src="original.jpg" width="100" height="50" />';
+        const result = replaceImagesWithPublicUrl(html);
+        expect(result).toBe('<img alt="photo" src="https://picsum.photos/seed/0/200/100" width="100" height="50" />');
+    });
+    it("handles attributes between width and height", () => {
+        const html = '<img src="original.jpg" width="100" alt="photo" height="50" />';
+        const result = replaceImagesWithPublicUrl(html);
+        expect(result).toBe('<img src="https://picsum.photos/seed/0/200/100" width="100" alt="photo" height="50" />');
+    });
+    it("handles attributes after width and height", () => {
+        const html = '<img src="original.jpg" width="100" height="50" alt="photo" />';
+        const result = replaceImagesWithPublicUrl(html);
+        expect(result).toBe('<img src="https://picsum.photos/seed/0/200/100" width="100" height="50" alt="photo" />');
+    });
+    it("leaves img tags without width untouched", () => {
+        const html = '<img src="original.jpg" height="200" />';
+        const result = replaceImagesWithPublicUrl(html);
+        expect(result).toBe('<img src="original.jpg" height="200" />');
+    });
+    it("leaves img tags without height untouched", () => {
+        const html = '<img src="original.jpg" width="300" />';
+        const result = replaceImagesWithPublicUrl(html);
+        expect(result).toBe('<img src="original.jpg" width="300" />');
+    });
+    it("increments seed for each image", () => {
+        const html = '<img src="a.jpg" width="100" height="100" /><img src="b.jpg" width="200" height="150" />';
+        const result = replaceImagesWithPublicUrl(html);
+        expect(result).toBe('<img src="https://picsum.photos/seed/0/200/200" width="100" height="100" />' +
+            '<img src="https://picsum.photos/seed/1/400/300" width="200" height="150" />');
+    });
+    it("returns unchanged html when there are no img tags", () => {
+        const html = "<p>Hello world</p>";
+        const result = replaceImagesWithPublicUrl(html);
+        expect(result).toBe("<p>Hello world</p>");
+    });
+    it("handles non-self-closing img tags", () => {
+        const html = '<img src="original.jpg" width="100" height="50">';
+        const result = replaceImagesWithPublicUrl(html);
+        expect(result).toBe('<img src="https://picsum.photos/seed/0/200/100" width="100" height="50">');
+    });
+});

package/lib/styles/Styles.d.ts

@@ -0,0 +1,6 @@
+import type { ReactNode } from "react";
+/**
+ * Internal component that iterates the styles registry and renders one
+ * `<MjmlStyle>` element per entry.
+ */
+export declare function Styles(): ReactNode;

package/lib/styles/Styles.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { MjmlStyle } from "@faire/mjml-react";
+import { useTheme } from "../theme/ThemeProvider.js";
+import { getRegisteredStyles } from "./registerStyles.js";
+/**
+ * Internal component that iterates the styles registry and renders one
+ * `<MjmlStyle>` element per entry.
+ */
+export function Styles() {
+    const theme = useTheme();
+    const entries = Array.from(getRegisteredStyles().values());
+    return (_jsx(_Fragment, { children: entries.map((entry, index) => {
+            const cssString = typeof entry.styles === "function" ? entry.styles(theme) : entry.styles;
+            return (_jsx(MjmlStyle, { ...entry.mjmlStyleProps, children: cssString }, index));
+        }) }));
+}

package/lib/styles/registerStyles.d.ts

@@ -0,0 +1,19 @@
+import type { IMjmlStyleProps } from "@faire/mjml-react";
+import type { Theme } from "../theme/themeTypes.js";
+import type { css } from "../utils/css.js";
+type StylesPayload = ReturnType<typeof css> | ((theme: Theme) => ReturnType<typeof css>);
+type MjmlStyleOptions = Partial<Omit<IMjmlStyleProps, "children">>;
+interface StyleRegistryEntry {
+    styles: StylesPayload;
+    mjmlStyleProps?: MjmlStyleOptions;
+}
+/**
+ * Registers CSS styles that will be rendered in the email head as `<mj-style>` elements.
+ *
+ * Styles can be static CSS strings (via the `css` tagged template) or functions that
+ * receive the theme and return a CSS string.
+ */
+export declare function registerStyles(styles: StylesPayload, mjmlStyleProps?: MjmlStyleOptions): void;
+/** Returns all registered style entries. */
+export declare function getRegisteredStyles(): ReadonlyMap<StylesPayload, StyleRegistryEntry>;
+export {};

package/lib/styles/registerStyles.js

@@ -0,0 +1,14 @@
+const registry = new Map();
+/**
+ * Registers CSS styles that will be rendered in the email head as `<mj-style>` elements.
+ *
+ * Styles can be static CSS strings (via the `css` tagged template) or functions that
+ * receive the theme and return a CSS string.
+ */
+export function registerStyles(styles, mjmlStyleProps) {
+    registry.set(styles, { styles, mjmlStyleProps });
+}
+/** Returns all registered style entries. */
+export function getRegisteredStyles() {
+    return registry;
+}

package/lib/theme/ThemeProvider.d.ts

@@ -0,0 +1,8 @@
+import { type PropsWithChildren, type ReactNode } from "react";
+import type { Theme } from "./themeTypes.js";
+export declare function ThemeProvider({ theme, children }: PropsWithChildren<{
+    theme: Theme;
+}>): ReactNode;
+export declare function useTheme(): Theme;
+/** Returns the current theme or `null` if no `ThemeProvider` is present. Internal use only. */
+export declare function useOptionalTheme(): Theme | null;

package/lib/theme/ThemeProvider.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const ThemeContext = createContext(null);
+export function ThemeProvider({ theme, children }) {
+    return _jsx(ThemeContext.Provider, { value: theme, children: children });
+}
+export function useTheme() {
+    const theme = useContext(ThemeContext);
+    if (theme === null) {
+        throw new Error("useTheme must be used within a ThemeProvider (or MjmlMailRoot).");
+    }
+    return theme;
+}
+/** Returns the current theme or `null` if no `ThemeProvider` is present. Internal use only. */
+export function useOptionalTheme() {
+    return useContext(ThemeContext);
+}

package/lib/theme/__stories__/ThemeProvider.stories.d.ts

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

package/lib/theme/__stories__/ThemeProvider.stories.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { MjmlColumn, MjmlText } from "@faire/mjml-react";
+import { MjmlSection } from "../../components/section/MjmlSection.js";
+import { createBreakpoint } from "../createBreakpoint.js";
+import { createTheme } from "../createTheme.js";
+import { ThemeProvider } from "../ThemeProvider.js";
+const config = {
+    title: "Components/ThemeProvider",
+    component: ThemeProvider,
+    tags: ["autodocs"],
+};
+export default config;
+export const Basic = {
+    render: () => (_jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsx(MjmlText, { children: "Using the default theme from the decorator." }) }) })),
+};
+const narrowTheme = createTheme({
+    sizes: { bodyWidth: 400 },
+    breakpoints: { mobile: createBreakpoint(360) },
+});
+export const CustomTheme = {
+    parameters: { theme: narrowTheme },
+    render: () => (_jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsx(MjmlText, { children: "This email uses a 400px body width and 360px mobile breakpoint." }) }) })),
+};

package/lib/theme/createBreakpoint.d.ts

@@ -0,0 +1,7 @@
+import type { ThemeBreakpoint } from "./themeTypes.js";
+/**
+ * Constructs a `ThemeBreakpoint` for use in `createTheme` overrides or
+ * `ThemeBreakpoints` module augmentation. Guarantees the `belowMediaQuery`
+ * string is always formatted correctly.
+ */
+export declare function createBreakpoint(value: number): ThemeBreakpoint;

package/lib/theme/createBreakpoint.js

@@ -0,0 +1,11 @@
+/**
+ * Constructs a `ThemeBreakpoint` for use in `createTheme` overrides or
+ * `ThemeBreakpoints` module augmentation. Guarantees the `belowMediaQuery`
+ * string is always formatted correctly.
+ */
+export function createBreakpoint(value) {
+    return {
+        value,
+        belowMediaQuery: `@media (max-width: ${value - 1}px)`,
+    };
+}

package/lib/theme/createTheme.d.ts

@@ -0,0 +1,22 @@
+import type { Theme, ThemeBackgroundColors, ThemeBreakpoints, ThemeColors, ThemeSizes, ThemeText } from "./themeTypes.js";
+type CreateThemeOverrides = {
+    sizes?: Partial<ThemeSizes>;
+    breakpoints?: Partial<ThemeBreakpoints>;
+    text?: Partial<ThemeText>;
+    colors?: {
+        background?: Partial<ThemeBackgroundColors>;
+    } & Partial<Omit<ThemeColors, "background">>;
+};
+/**
+ * Creates a complete theme by merging optional overrides onto the default
+ * theme values.
+ *
+ * Breakpoint overrides must be `ThemeBreakpoint` objects constructed via
+ * `createBreakpoint`. Arbitrary breakpoint keys from `ThemeBreakpoints`
+ * module augmentation are supported and flow through to the result.
+ *
+ * `breakpoints.default` is always auto-derived from `sizes.bodyWidth` unless
+ * explicitly overridden.
+ */
+export declare function createTheme(overrides?: CreateThemeOverrides): Theme;
+export {};

package/lib/theme/createTheme.js

@@ -0,0 +1,30 @@
+import { createBreakpoint } from "./createBreakpoint.js";
+import { defaultTheme } from "./defaultTheme.js";
+/**
+ * Creates a complete theme by merging optional overrides onto the default
+ * theme values.
+ *
+ * Breakpoint overrides must be `ThemeBreakpoint` objects constructed via
+ * `createBreakpoint`. Arbitrary breakpoint keys from `ThemeBreakpoints`
+ * module augmentation are supported and flow through to the result.
+ *
+ * `breakpoints.default` is always auto-derived from `sizes.bodyWidth` unless
+ * explicitly overridden.
+ */
+export function createTheme(overrides) {
+    const resolvedSizes = { ...defaultTheme.sizes, ...overrides?.sizes };
+    return {
+        sizes: resolvedSizes,
+        breakpoints: {
+            ...defaultTheme.breakpoints,
+            default: createBreakpoint(resolvedSizes.bodyWidth),
+            ...overrides?.breakpoints,
+        },
+        text: { ...defaultTheme.text, ...overrides?.text },
+        colors: {
+            ...defaultTheme.colors,
+            ...overrides?.colors,
+            background: { ...defaultTheme.colors.background, ...overrides?.colors?.background },
+        },
+    };
+}

package/lib/theme/createTheme.test.d.ts

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