@comet/mail-react 8.20.2 → 9.0.0-beta.1

package/README.md

@@ -0,0 +1,26 @@
+# @comet/mail-react
+
+Utilities for building HTML emails with React and MJML.
+
+## Spec-driven development with OpenSpec
+
+This package uses [OpenSpec](https://github.com/Fission-AI/OpenSpec) for spec-driven development. Specs and change history live in `openspec/` and are committed to the repo.
+
+## Getting started
+
+- Run `./install.sh` from the project root to install dependencies and configure OpenSpec agent skills
+- Open the `packages/mail-react/` directory directly in the IDE, as OpenSpec does not currently support monorepos
+
+## Suggested development workflow
+
+- Use `/opsx:explore` to think through ideas before proposing
+- Use `/opsx:propose` to propose a change, then commit the proposal
+- Use `/opsx:apply` to apply the change, then commit the result
+- Use `/opsx:archive` to archive the change and merge delta specs into the main specs, then commit
+
+Minor fixes may skip this workflow if they do not create a gap between `openspec/specs/` and the code (e.g. changing a TSDoc comment).
+
+## Suggested review workflow
+
+- A pull request should propose, apply, and archive a change in one go
+- Reviewers can then focus on the code changes and resulting spec, skimming the archived implementation details

package/lib/client/index.d.ts

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

package/lib/client/index.js

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

package/lib/client/renderMailHtml.d.ts

@@ -0,0 +1,9 @@
+import mjml2html from "mjml-browser";
+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/client/renderMailHtml.js

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

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

@@ -0,0 +1,22 @@
+import type { PropsWithChildren, ReactNode } from "react";
+import type { Theme } from "../../theme/themeTypes.js";
+type MjmlMailRootProps = PropsWithChildren<{
+    /**
+     * Theme to use for the email. When omitted, the default theme
+     * (equivalent to `createTheme()`) is used.
+     */
+    theme?: Theme;
+}>;
+/**
+ * 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()`.
+ *
+ * Direct children should be section-level components (e.g. `MjmlSection`).
+ */
+export declare function MjmlMailRoot({ theme: themeProp, children }: MjmlMailRootProps): ReactNode;
+export {};

package/lib/components/mailRoot/MjmlMailRoot.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Mjml, MjmlAll, MjmlAttributes, MjmlBody, MjmlBreakpoint, MjmlHead } from "@faire/mjml-react";
+import { Styles } from "../../styles/Styles.js";
+import { createTheme } from "../../theme/createTheme.js";
+import { ThemeProvider } from "../../theme/ThemeProvider.js";
+/**
+ * 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()`.
+ *
+ * Direct children should be section-level components (e.g. `MjmlSection`).
+ */
+export function MjmlMailRoot({ theme: themeProp, children }) {
+    const theme = themeProp ?? createTheme();
+    return (_jsx(ThemeProvider, { theme: theme, children: _jsxs(Mjml, { children: [_jsxs(MjmlHead, { children: [_jsx(MjmlAttributes, { children: _jsx(MjmlAll, { padding: "0" }) }), _jsx(MjmlBreakpoint, { width: `${theme.breakpoints.mobile.value}px` }), _jsx(Styles, {})] }), _jsx(MjmlBody, { width: theme.sizes.bodyWidth, children: children })] }) }));
+}

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

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

package/lib/components/mailRoot/__stories__/MjmlMailRoot.stories.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { MjmlColumn, MjmlText } from "@faire/mjml-react";
+import { MjmlSection } from "../../section/MjmlSection.js";
+import { MjmlMailRoot } from "../MjmlMailRoot.js";
+const config = {
+    title: "Components/MjmlMailRoot",
+    component: MjmlMailRoot,
+    tags: ["autodocs"],
+};
+export default config;
+export const Basic = {
+    render: () => (_jsx(MjmlMailRoot, { children: _jsx(MjmlSection, { children: _jsx(MjmlColumn, { children: _jsx(MjmlText, { children: "Hello from MjmlMailRoot" }) }) }) })),
+};

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

@@ -0,0 +1,15 @@
+import { type IMjmlGroupProps, type IMjmlSectionProps } from "@faire/mjml-react";
+import type { ReactNode } from "react";
+export type MjmlSectionProps = IMjmlSectionProps & {
+    /** Applies theme-based content indentation with responsive overrides. */
+    indent?: boolean;
+    /** When true, child columns remain side-by-side on mobile instead of stacking vertically. */
+    disableResponsiveBehavior?: boolean;
+    /** Props forwarded to internal sub-components. */
+    slotProps?: {
+        /** Props passed to the wrapping `MjmlGroup` when `disableResponsiveBehavior` is enabled. */
+        group?: Partial<IMjmlGroupProps>;
+    };
+};
+/** A section wrapper for email layouts. Must be a direct child of `MjmlBody`. */
+export declare function MjmlSection({ children, indent, disableResponsiveBehavior, slotProps, className, ...props }: MjmlSectionProps): ReactNode;

package/lib/components/section/MjmlSection.js

@@ -0,0 +1,43 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { MjmlGroup, MjmlSection as BaseMjmlSection } from "@faire/mjml-react";
+import clsx from "clsx";
+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`. */
+export function MjmlSection({ children, indent, disableResponsiveBehavior, slotProps, className, ...props }) {
+    const theme = useOptionalTheme();
+    const indentProps = indent ? getIndentProps(theme) : {};
+    const resolvedClassName = clsx("mjmlSection", indent && "mjmlSection--indented", className);
+    return (_jsx(BaseMjmlSection, { className: resolvedClassName, ...indentProps, ...props, children: disableResponsiveBehavior ? _jsx(MjmlGroup, { ...slotProps?.group, children: children }) : _jsx(_Fragment, { children: children }) }));
+}
+function getIndentProps(theme) {
+    if (theme === null) {
+        throw new Error("The `indent` prop requires being wrapped in a ThemeProvider or MjmlMailRoot.");
+    }
+    return {
+        paddingLeft: getDefaultFromResponsiveValue(theme.sizes.contentIndentation),
+        paddingRight: getDefaultFromResponsiveValue(theme.sizes.contentIndentation),
+    };
+}
+registerStyles((theme) => {
+    const overrides = getResponsiveOverrides(theme.sizes.contentIndentation);
+    if (overrides.length === 0)
+        return css ``;
+    return overrides
+        .map((override) => {
+        const breakpoint = theme.breakpoints[override.breakpointKey];
+        if (!breakpoint)
+            return "";
+        return css `
+                ${breakpoint.belowMediaQuery} {
+                    .mjmlSection--indented > table > tbody > tr > td {
+                        padding-left: ${override.value}px !important;
+                        padding-right: ${override.value}px !important;
+                    }
+                }
+            `;
+    })
+        .join("\n");
+});

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

@@ -0,0 +1,8 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { MjmlSection } from "../MjmlSection.js";
+type Story = StoryObj<typeof MjmlSection>;
+declare const config: Meta<typeof MjmlSection>;
+export default config;
+export declare const Primary: Story;
+export declare const Indented: Story;
+export declare const DisabledResponsiveBehavior: Story;

package/lib/components/section/__stories__/MjmlSection.stories.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MjmlColumn, MjmlText } from "@faire/mjml-react";
+import { MjmlSection } from "../MjmlSection.js";
+const config = {
+    title: "Components/MjmlSection",
+    component: MjmlSection,
+    tags: ["autodocs"],
+};
+export default config;
+export const Primary = {
+    render: (args) => (_jsx(MjmlSection, { ...args, children: _jsx(MjmlColumn, { children: _jsx(MjmlText, { children: "Section content" }) }) })),
+};
+export const Indented = {
+    args: {
+        indent: true,
+    },
+    render: (args) => (_jsx(MjmlSection, { ...args, children: _jsx(MjmlColumn, { children: _jsx(MjmlText, { children: "Indented section content" }) }) })),
+};
+export const DisabledResponsiveBehavior = {
+    args: {
+        disableResponsiveBehavior: true,
+    },
+    render: (args) => (_jsxs(MjmlSection, { ...args, children: [_jsx(MjmlColumn, { children: _jsx(MjmlText, { children: "First column" }) }), _jsx(MjmlColumn, { children: _jsx(MjmlText, { children: "Second column" }) })] })),
+};

package/lib/index.d.ts

@@ -4,7 +4,17 @@ 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 { MjmlMailRoot } from "./components/mailRoot/MjmlMailRoot.js";
+export type { MjmlSectionProps } from "./components/section/MjmlSection.js";
+export { MjmlSection } from "./components/section/MjmlSection.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 { Theme, ThemeBreakpoint, ThemeBreakpoints, ThemeSizes } 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, MjmlText, type IMjmlTextProps as MjmlTextProps, 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,14 @@ 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 { MjmlMailRoot } from "./components/mailRoot/MjmlMailRoot.js";
+export { MjmlSection } from "./components/section/MjmlSection.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, MjmlText, 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 @@
+export declare function MailRendererDecorator(Story: () => React.JSX.Element): 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) {
+    const [globals] = useGlobals();
+    const emit = useChannel({});
+    const { html: rawHtml, mjmlWarnings } = renderMailHtml(_jsx(MjmlMailRoot, { 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, { 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, { 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,18 @@
+import type { Theme, ThemeBreakpoints, ThemeSizes } from "./themeTypes.js";
+type CreateThemeOverrides = {
+    sizes?: Partial<ThemeSizes>;
+    breakpoints?: Partial<ThemeBreakpoints>;
+};
+/**
+ * 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,24 @@
+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,
+        },
+    };
+}

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

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

package/lib/theme/createTheme.test.js

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { createTheme } from "./createTheme.js";
+import { getDefaultFromResponsiveValue, getResponsiveOverrides } from "./responsiveValue.js";
+describe("createTheme contentIndentation", () => {
+    it("has default contentIndentation with responsive mobile value", () => {
+        const theme = createTheme();
+        expect(getDefaultFromResponsiveValue(theme.sizes.contentIndentation)).toBe(32);
+        expect(getResponsiveOverrides(theme.sizes.contentIndentation)).toContainEqual({ breakpointKey: "mobile", value: 16 });
+    });
+    it("allows overriding contentIndentation with a plain number", () => {
+        const theme = createTheme({ sizes: { contentIndentation: 30 } });
+        expect(getDefaultFromResponsiveValue(theme.sizes.contentIndentation)).toBe(30);
+        expect(getResponsiveOverrides(theme.sizes.contentIndentation)).toEqual([]);
+    });
+    it("allows overriding contentIndentation with an object", () => {
+        const theme = createTheme({ sizes: { contentIndentation: { default: 30, mobile: 15 } } });
+        expect(getDefaultFromResponsiveValue(theme.sizes.contentIndentation)).toBe(30);
+        expect(getResponsiveOverrides(theme.sizes.contentIndentation)).toContainEqual({ breakpointKey: "mobile", value: 15 });
+    });
+});

package/lib/theme/defaultTheme.d.ts

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

package/lib/theme/defaultTheme.js

@@ -0,0 +1,11 @@
+import { createBreakpoint } from "./createBreakpoint.js";
+export const defaultTheme = {
+    sizes: {
+        bodyWidth: 600,
+        contentIndentation: { default: 32, mobile: 16 },
+    },
+    breakpoints: {
+        default: createBreakpoint(600),
+        mobile: createBreakpoint(420),
+    },
+};

package/lib/theme/responsiveValue.d.ts

@@ -0,0 +1,25 @@
+import type { ThemeBreakpoints } from "./themeTypes.js";
+/**
+ * A value that can vary per breakpoint. A plain `T` is shorthand for
+ * `{ default: T }` (inline only, no responsive overrides).
+ *
+ * The object form requires a `default` key and optional keys matching
+ * `ThemeBreakpoints` (including keys added via module augmentation).
+ */
+export type ResponsiveValue<T = number> = T | (Partial<Record<keyof ThemeBreakpoints, T>> & {
+    default: T;
+});
+/**
+ * Returns the default (inline) value from a `ResponsiveValue`.
+ * For a plain value, returns it directly. For an object, returns the `default` property.
+ */
+export declare function getDefaultFromResponsiveValue<T = number>(value: ResponsiveValue<T>): T;
+/**
+ * Returns the non-default breakpoint overrides from a `ResponsiveValue`.
+ * For a plain value, returns an empty array. For an object, returns one
+ * entry per breakpoint key (excluding `default`).
+ */
+export declare function getResponsiveOverrides<T = number>(value: ResponsiveValue<T>): Array<{
+    breakpointKey: keyof ThemeBreakpoints;
+    value: T;
+}>;

package/lib/theme/responsiveValue.js

@@ -0,0 +1,23 @@
+function isResponsiveObject(value) {
+    return typeof value === "object" && value !== null && "default" in value;
+}
+/**
+ * Returns the default (inline) value from a `ResponsiveValue`.
+ * For a plain value, returns it directly. For an object, returns the `default` property.
+ */
+export function getDefaultFromResponsiveValue(value) {
+    return isResponsiveObject(value) ? value.default : value;
+}
+/**
+ * Returns the non-default breakpoint overrides from a `ResponsiveValue`.
+ * For a plain value, returns an empty array. For an object, returns one
+ * entry per breakpoint key (excluding `default`).
+ */
+export function getResponsiveOverrides(value) {
+    if (!isResponsiveObject(value)) {
+        return [];
+    }
+    return Object.entries(value)
+        .filter(([key]) => key !== "default")
+        .map(([key, val]) => ({ breakpointKey: key, value: val }));
+}

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

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

package/lib/theme/responsiveValue.test.js

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { getDefaultFromResponsiveValue, getResponsiveOverrides } from "./responsiveValue.js";
+describe("getDefaultFromResponsiveValue", () => {
+    it("returns the value when given a plain number", () => {
+        expect(getDefaultFromResponsiveValue(20)).toBe(20);
+    });
+    it("returns the default property from an object", () => {
+        expect(getDefaultFromResponsiveValue({ default: 20, mobile: 10 })).toBe(20);
+    });
+    it("returns the default property when only default is present", () => {
+        expect(getDefaultFromResponsiveValue({ default: 42 })).toBe(42);
+    });
+    it("works with string type", () => {
+        expect(getDefaultFromResponsiveValue({ default: "24px", mobile: "20px" })).toBe("24px");
+    });
+    it("returns a plain string value", () => {
+        expect(getDefaultFromResponsiveValue("24px")).toBe("24px");
+    });
+});
+describe("getResponsiveOverrides", () => {
+    it("returns an empty array for a plain number", () => {
+        expect(getResponsiveOverrides(20)).toEqual([]);
+    });
+    it("returns an empty array for an object with only default", () => {
+        expect(getResponsiveOverrides({ default: 42 })).toEqual([]);
+    });
+    it("returns overrides for non-default keys", () => {
+        const result = getResponsiveOverrides({ default: 20, mobile: 10 });
+        expect(result).toEqual([{ breakpointKey: "mobile", value: 10 }]);
+    });
+    it("returns multiple overrides for multiple breakpoint keys", () => {
+        const value = { default: 30, mobile: 10 };
+        const result = getResponsiveOverrides(value);
+        expect(result).toContainEqual({ breakpointKey: "mobile", value: 10 });
+        expect(result).not.toContainEqual(expect.objectContaining({ breakpointKey: "default" }));
+    });
+    it("never includes the default key in overrides", () => {
+        const result = getResponsiveOverrides({ default: 20, mobile: 10 });
+        expect(result.every((o) => o.breakpointKey !== "default")).toBe(true);
+    });
+    it("works with string type", () => {
+        const result = getResponsiveOverrides({ default: "24px", mobile: "20px" });
+        expect(result).toEqual([{ breakpointKey: "mobile", value: "20px" }]);
+    });
+});

package/lib/theme/themeTypes.d.ts

@@ -0,0 +1,47 @@
+import type { ResponsiveValue } from "./responsiveValue.js";
+/**
+ * A resolved breakpoint with its numeric value and a ready-to-use media query
+ * string that targets viewports narrower than this breakpoint.
+ */
+export interface ThemeBreakpoint {
+    /** The breakpoint width in pixels. */
+    value: number;
+    /** A CSS media query matching viewports below this breakpoint, e.g. `"@media (max-width: 599px)"`. */
+    belowMediaQuery: string;
+}
+/**
+ * Responsive breakpoints used by the email layout.
+ *
+ * The `default` breakpoint typically matches the body width, while `mobile`
+ * defines the narrow viewport threshold.
+ */
+export interface ThemeBreakpoints {
+    /** The default breakpoint, usually equal to `sizes.bodyWidth`. */
+    default: ThemeBreakpoint;
+    /**
+     * The mobile breakpoint — the viewport width below which the layout is
+     * considered "mobile".
+     *
+     * When used with `MjmlMailRoot`, this value also controls the MJML
+     * responsive breakpoint (`<mj-breakpoint>`), which determines the viewport
+     * width at which columns stack vertically.
+     */
+    mobile: ThemeBreakpoint;
+}
+/** Numeric size tokens for the email layout. */
+export interface ThemeSizes {
+    /** The width of the email body in pixels. */
+    bodyWidth: number;
+    /** Content indentation (left/right padding) in pixels, supporting per-breakpoint values. */
+    contentIndentation: ResponsiveValue;
+}
+/**
+ * The root theme object that holds all design tokens for `@comet/mail-react`.
+ *
+ * Every sub-interface is declared as an `interface` so consumers can
+ * extend the theme at any level via TypeScript module augmentation.
+ */
+export interface Theme {
+    sizes: ThemeSizes;
+    breakpoints: ThemeBreakpoints;
+}

package/lib/theme/themeTypes.js

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

package/lib/utils/css.test.d.ts

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

package/lib/utils/css.test.js

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { css } from "./css.js";
+describe("css tagged-template helper", () => {
+    it("returns static template text exactly", () => {
+        const result = css `
+            color: red;
+            font-size: 16px;
+        `;
+        expect(result).toBe(`
+            color: red;
+            font-size: 16px;
+        `);
+    });
+    it("resolves interpolated values correctly", () => {
+        const color = "blue";
+        const size = 14;
+        const result = css `
+            color: ${color};
+            font-size: ${size}px;
+        `;
+        expect(result).toBe(`
+            color: blue;
+            font-size: 14px;
+        `);
+    });
+});

package/package.json

@@ -1,35 +1,53 @@
 {
   "name": "@comet/mail-react",
-  "version": "8.20.2",
+  "version": "9.0.0-beta.1",
   "description": "Utilities for building HTML emails with React",
   "license": "BSD-2-Clause",
   "type": "module",
   "exports": {
-    ".": {
-      "types": "./lib/index.d.ts",
-      "default": "./lib/index.js"
-    }
+    ".": "./lib/index.js",
+    "./client": "./lib/client/index.js",
+    "./server": "./lib/server/index.js",
+    "./storybook": "./lib/storybook/index.js"
   },
   "files": [
     "lib/*"
   ],
   "dependencies": {
-    "@faire/mjml-react": "^3.5.3"
+    "@faire/mjml-react": "^3.5.3",
+    "clsx": "^2.1.1",
+    "mjml": "^4.18.0",
+    "mjml-browser": "^4.18.0"
   },
   "devDependencies": {
-    "@types/react": "^18.3.27",
+    "@fission-ai/openspec": "^1.2.0",
+    "@storybook/addon-docs": "^10.3.1",
+    "@storybook/react-vite": "^10.3.1",
+    "@types/mjml": "^4.7.4",
+    "@types/mjml-browser": "^4.15.0",
+    "@types/react": "^19.2.10",
+    "@types/react-dom": "^19.2.3",
     "chokidar-cli": "^3.0.0",
     "eslint": "^9.39.2",
     "npm-run-all2": "^8.0.4",
     "prettier": "^3.6.2",
-    "react": "^18.3.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "rimraf": "^6.1.2",
+    "storybook": "^10.3.1",
     "typescript": "^5.9.3",
-    "@comet/cli": "8.20.2",
-    "@comet/eslint-config": "8.20.2"
+    "vitest": "^4.0.16",
+    "@comet/cli": "9.0.0-beta.1",
+    "@comet/eslint-config": "9.0.0-beta.1"
   },
   "peerDependencies": {
-    "react": "^18.0.0"
+    "react": "^18.0.0 || ^19.0.0",
+    "storybook": ">=10.0.0"
+  },
+  "peerDependenciesMeta": {
+    "storybook": {
+      "optional": true
+    }
   },
   "engines": {
     "node": ">=22.0.0"
@@ -40,6 +58,7 @@
   },
   "scripts": {
     "build": "pnpm run clean && pnpm run generate-block-types && tsc",
+    "build-storybook": "storybook build",
     "clean": "rimraf lib 'src/**/*.generated.ts'",
     "dev": "pnpm run clean && pnpm generate-block-types && tsc --watch",
     "generate-block-types": "comet generate-block-types",
@@ -48,6 +67,10 @@
     "lint:ci": "pnpm run lint",
     "lint:eslint": "eslint --max-warnings 0 src/ '**/*.json' --no-warn-ignored",
     "lint:prettier": "pnpm exec prettier --check '*.{ts,js,json,md,yml,yaml}'",
-    "lint:tsc": "tsc"
+    "lint:tsc": "tsc",
+    "openspec:install-skills": "openspec init --tools github-copilot,cursor,claude",
+    "storybook": "storybook dev -p 6066 --no-open",
+    "test": "vitest --run",
+    "test:watch": "vitest --watch"
   }
 }