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

package/lib/__stories__/examples/CustomNestedFooterTheme.stories.d.ts

@@ -0,0 +1,5 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+declare const config: Meta;
+export default config;
+type Story = StoryObj;
+export declare const Default: Story;

package/lib/__stories__/examples/CustomNestedFooterTheme.stories.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MjmlColumn, MjmlSpacer, MjmlTable } from "@faire/mjml-react";
+import { HtmlInlineLink } from "../../components/inlineLink/HtmlInlineLink.js";
+import { MjmlMailRoot } from "../../components/mailRoot/MjmlMailRoot.js";
+import { MjmlSection } from "../../components/section/MjmlSection.js";
+import { HtmlText } from "../../components/text/HtmlText.js";
+import { MjmlText } from "../../components/text/MjmlText.js";
+import { createTheme } from "../../theme/createTheme.js";
+import { ThemeProvider } from "../../theme/ThemeProvider.js";
+const config = {
+    title: "Examples/CustomNestedFooterTheme",
+    parameters: { mailRoot: false },
+};
+export default config;
+export const Default = {
+    render: () => {
+        const theme = createTheme({
+            text: {
+                defaultVariant: "body",
+                variants: {
+                    heading: { fontSize: "22px", lineHeight: "28px", fontWeight: "bold" },
+                    body: { fontSize: "14px", lineHeight: "20px" },
+                    legal: { fontSize: "12px", lineHeight: "18px" },
+                },
+            },
+        });
+        const footerTheme = structuredClone(theme);
+        footerTheme.colors.background.content = "#2d4a6e";
+        footerTheme.text.color = "#c8d8e9";
+        return (_jsxs(MjmlMailRoot, { theme: theme, children: [_jsx(MjmlSection, { backgroundColor: "#1a1a1a", indent: true, children: _jsxs(MjmlColumn, { children: [_jsx(MjmlSpacer, { height: 15 }), _jsx(MjmlText, { color: "#ffffff", fontWeight: "bold", align: "center", children: "Company Name" }), _jsx(MjmlSpacer, { height: 15 })] }) }), _jsx(MjmlSection, { indent: true, children: _jsxs(MjmlColumn, { children: [_jsx(MjmlSpacer, { height: 30 }), _jsx(MjmlText, { variant: "heading", bottomSpacing: true, children: "This is a notification email" }), _jsx(MjmlText, { bottomSpacing: true, children: "Minima ea distinctio quisquam. Illo reiciendis non officiis consectetur. Ratione perferendis distinctio sapiente est. Dolor consequatur qui excepturi natus." }), _jsx(MjmlText, { children: "Numquam aut voluptas numquam aspernatur. Consequatur quidem omnis dolorem natus quis soluta. Est recusandae delectus sed sed deserunt velit quia. Occaecati vel possimus similique reiciendis possimus iure rerum sit architecto." }), _jsx(MjmlSpacer, { height: 30 })] }) }), _jsxs(ThemeProvider, { theme: footerTheme, children: [_jsx(MjmlSection, { indent: true, children: _jsxs(MjmlColumn, { children: [_jsx(MjmlSpacer, { height: 20 }), _jsx(MjmlText, { align: "center", bottomSpacing: true, children: "\u00A9 2026 Company Name \u2013 All rights reserved" }), _jsx(MjmlText, { variant: "legal", align: "center", bottomSpacing: true, children: "Legal text, corporis eos et quia. Assumenda eum maiores esse. Voluptas laudantium cupiditate aut repudiandae iste fugiat nam. Quas in debitis. Sed laudantium illum aut occaecati excepturi veniam harum reprehenderit." })] }) }), _jsx(MjmlSection, { indent: true, children: _jsxs(MjmlColumn, { children: [_jsx(MjmlTable, { width: "auto", align: "center", children: _jsx("tbody", { children: _jsxs("tr", { children: [_jsx(HtmlText, { align: "center", children: _jsx(HtmlInlineLink, { href: "https://example.com/privacy", children: "Privacy Policy" }) }), _jsx("td", { width: "20px" }), _jsx(HtmlText, { align: "center", children: _jsx(HtmlInlineLink, { href: "https://example.com/imprint", children: "Imprint" }) }), _jsx("td", { width: "20px" }), _jsx(HtmlText, { align: "center", children: _jsx(HtmlInlineLink, { href: "https://example.com", children: "Website" }) })] }) }) }), _jsx(MjmlSpacer, { height: 20 })] }) })] })] }));
+    },
+};

package/lib/__stories__/examples/NotificationEmail.stories.d.ts

@@ -0,0 +1,5 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+declare const config: Meta;
+export default config;
+type Story = StoryObj;
+export declare const Default: Story;

package/lib/__stories__/examples/NotificationEmail.stories.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MjmlColumn, MjmlSpacer } from "@faire/mjml-react";
+import { MjmlMailRoot } from "../../components/mailRoot/MjmlMailRoot.js";
+import { MjmlSection } from "../../components/section/MjmlSection.js";
+import { MjmlText } from "../../components/text/MjmlText.js";
+import { createTheme } from "../../theme/createTheme.js";
+const config = {
+    title: "Examples/NotificationEmail",
+    parameters: { mailRoot: false },
+};
+export default config;
+export const Default = {
+    render: () => {
+        const theme = createTheme({
+            text: {
+                defaultVariant: "body",
+                variants: {
+                    heading: { fontSize: "22px", lineHeight: "28px", fontWeight: "bold" },
+                    body: { fontSize: "16px", lineHeight: "24px" },
+                },
+            },
+        });
+        return (_jsxs(MjmlMailRoot, { theme: theme, children: [_jsx(MjmlSection, { backgroundColor: "#1a1a1a", indent: true, children: _jsxs(MjmlColumn, { children: [_jsx(MjmlSpacer, { height: 15 }), _jsx(MjmlText, { color: "#ffffff", fontWeight: "bold", align: "center", children: "Company Name" }), _jsx(MjmlSpacer, { height: 15 })] }) }), _jsx(MjmlSection, { indent: true, children: _jsxs(MjmlColumn, { children: [_jsx(MjmlSpacer, { height: 30 }), _jsx(MjmlText, { variant: "heading", bottomSpacing: true, children: "This is a notification email" }), _jsx(MjmlText, { bottomSpacing: true, children: "Minima ea distinctio quisquam. Illo reiciendis non officiis consectetur. Ratione perferendis distinctio sapiente est. Dolor consequatur qui excepturi natus." }), _jsx(MjmlText, { children: "Numquam aut voluptas numquam aspernatur. Consequatur quidem omnis dolorem natus quis soluta. Est recusandae delectus sed sed deserunt velit quia. Occaecati vel possimus similique reiciendis possimus iure rerum sit architecto." }), _jsx(MjmlSpacer, { height: 30 })] }) })] }));
+    },
+};

package/lib/__stories__/examples/TextWithImageEmail.stories.d.ts

@@ -0,0 +1,5 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+declare const config: Meta;
+export default config;
+type Story = StoryObj;
+export declare const Default: Story;

package/lib/__stories__/examples/TextWithImageEmail.stories.js

@@ -0,0 +1,56 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MjmlColumn, MjmlImage, MjmlSpacer } from "@faire/mjml-react";
+import { MjmlMailRoot } from "../../components/mailRoot/MjmlMailRoot.js";
+import { MjmlSection } from "../../components/section/MjmlSection.js";
+import { MjmlText } from "../../components/text/MjmlText.js";
+import { registerStyles } from "../../styles/registerStyles.js";
+import { createTheme } from "../../theme/createTheme.js";
+import { getDefaultFromResponsiveValue } from "../../theme/responsiveValue.js";
+import { css } from "../../utils/css.js";
+const config = {
+    title: "Examples/TextWithImageEmail",
+    parameters: { mailRoot: false },
+};
+export default config;
+export const Default = {
+    render: () => {
+        const theme = createTheme({
+            text: {
+                defaultVariant: "body",
+                variants: {
+                    heading: { fontSize: "22px", lineHeight: "28px", fontWeight: "bold" },
+                    body: { fontSize: "16px", lineHeight: "24px" },
+                },
+            },
+        });
+        const IMAGE_WIDTH = 120;
+        const IMAGE_TEXT_GAP = 20;
+        registerStyles((theme) => css `
+                ${theme.breakpoints.default.belowMediaQuery} {
+                    .textWithImageEmail__textColumn {
+                        width: calc(100% - ${IMAGE_WIDTH}px) !important;
+                        max-width: calc(100% - ${IMAGE_WIDTH}px) !important;
+                    }
+                }
+
+                ${theme.breakpoints.mobile.belowMediaQuery} {
+                    .textWithImageEmail__imageColumn {
+                        margin-bottom: 10px;
+                    }
+
+                    .textWithImageEmail__textColumn {
+                        width: 100% !important;
+                        max-width: 100% !important;
+                    }
+
+                    .textWithImageEmail__textColumn > table > tbody > tr > td {
+                        padding-left: 0 !important;
+                    }
+                }
+            `);
+        const sectionIndent = getDefaultFromResponsiveValue(theme.sizes.contentIndentation);
+        const sectionInnerWidth = theme.sizes.bodyWidth - 2 * sectionIndent;
+        const textColumnWidth = sectionInnerWidth - IMAGE_WIDTH;
+        return (_jsxs(MjmlMailRoot, { theme: theme, children: [_jsx(MjmlSection, { backgroundColor: "#1a1a1a", indent: true, children: _jsxs(MjmlColumn, { children: [_jsx(MjmlSpacer, { height: 15 }), _jsx(MjmlText, { color: "#ffffff", fontWeight: "bold", align: "center", children: "Company Name" }), _jsx(MjmlSpacer, { height: 15 })] }) }), _jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsx(MjmlSpacer, { height: 30 }) }) }), _jsxs(MjmlSection, { indent: true, children: [_jsx(MjmlColumn, { className: "textWithImageEmail__imageColumn", width: `${IMAGE_WIDTH}px`, verticalAlign: "middle", children: _jsx(MjmlImage, { src: `https://picsum.photos/seed/1/${IMAGE_WIDTH}/150`, alt: "Featured image", align: "center", width: IMAGE_WIDTH }) }), _jsxs(MjmlColumn, { className: "textWithImageEmail__textColumn", width: `${textColumnWidth}px`, paddingLeft: `${IMAGE_TEXT_GAP}px`, verticalAlign: "middle", children: [_jsx(MjmlText, { variant: "heading", bottomSpacing: true, children: "Responsive Text-Image" }), _jsx(MjmlText, { children: "Demonstrates a responsive text-image layout with a fixed-width image column and a text column taking up remaining space." })] })] }), _jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsx(MjmlSpacer, { height: 30 }) }) })] }));
+    },
+};

package/lib/components/inlineLink/HtmlInlineLink.d.ts

@@ -0,0 +1,10 @@
+import type { ComponentProps, ReactNode } from "react";
+export type HtmlInlineLinkProps = ComponentProps<"a">;
+/**
+ * Inline link styled to match the surrounding text, for use inside `HtmlText` or `MjmlText`.
+ *
+ * Applies explicit text styles from the parent text component's context so that
+ * Outlook Desktop (which overrides `<a>` tags with its built-in "Hyperlink" style)
+ * renders the link with the correct font and color.
+ */
+export declare function HtmlInlineLink({ className, style, target, ...restProps }: HtmlInlineLinkProps): ReactNode;

package/lib/components/inlineLink/HtmlInlineLink.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import clsx from "clsx";
+import { registerStyles } from "../../styles/registerStyles.js";
+import { css } from "../../utils/css.js";
+import { useOutlookTextStyle } from "../text/OutlookTextStyleContext.js";
+/**
+ * Inline link styled to match the surrounding text, for use inside `HtmlText` or `MjmlText`.
+ *
+ * Applies explicit text styles from the parent text component's context so that
+ * Outlook Desktop (which overrides `<a>` tags with its built-in "Hyperlink" style)
+ * renders the link with the correct font and color.
+ */
+export function HtmlInlineLink({ className, style, target = "_blank", ...restProps }) {
+    const outlookTextStyle = useOutlookTextStyle();
+    const baseStyle = {
+        fontFamily: outlookTextStyle?.fontFamily ?? "inherit",
+        fontSize: outlookTextStyle?.fontSize ?? "inherit",
+        lineHeight: outlookTextStyle?.lineHeight ?? "inherit",
+        fontWeight: outlookTextStyle?.fontWeight ?? "inherit",
+        color: outlookTextStyle?.color ?? "inherit",
+        textDecoration: "underline",
+    };
+    return _jsx("a", { className: clsx("htmlInlineLink", className), style: { ...baseStyle, ...style }, target: target, ...restProps });
+}
+registerStyles((theme) => css `
+        ${theme.breakpoints.default.belowMediaQuery} {
+            .htmlInlineLink {
+                font-family: inherit !important;
+                font-size: inherit !important;
+                line-height: inherit !important;
+                font-weight: inherit !important;
+                color: inherit !important;
+            }
+        }
+    `);

package/lib/components/inlineLink/__stories__/HtmlInlineLink.stories.d.ts

@@ -0,0 +1,12 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { HtmlInlineLink } from "../HtmlInlineLink.js";
+type Story = StoryObj<typeof HtmlInlineLink>;
+declare const config: Meta<typeof HtmlInlineLink>;
+export default config;
+export declare const InText: Story;
+/**
+ * Using `!important` overrides the component's responsive `inherit !important`
+ * reset, ensuring the custom color persists on both desktop and mobile.
+ */
+export declare const CustomColorOverride: Story;
+export declare const WithTextVariants: Story;

package/lib/components/inlineLink/__stories__/HtmlInlineLink.stories.js

@@ -0,0 +1,56 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MjmlColumn } from "@faire/mjml-react";
+import { createTheme } from "../../../theme/createTheme.js";
+import { MjmlSection } from "../../section/MjmlSection.js";
+import { MjmlText } from "../../text/MjmlText.js";
+import { HtmlInlineLink } from "../HtmlInlineLink.js";
+const config = {
+    title: "Components/HtmlInlineLink",
+    component: HtmlInlineLink,
+    tags: ["autodocs"],
+};
+export default config;
+export const InText = {
+    parameters: {
+        theme: createTheme({
+            text: {
+                fontFamily: "Arial, sans-serif",
+                fontSize: "16px",
+                lineHeight: "24px",
+                color: "#333333",
+            },
+        }),
+    },
+    render: () => (_jsx(MjmlSection, { children: _jsx(MjmlColumn, { children: _jsxs(MjmlText, { children: ["Visit our ", _jsx(HtmlInlineLink, { href: "https://example.com", children: "website" }), " for more information."] }) }) })),
+};
+/**
+ * Using `!important` overrides the component's responsive `inherit !important`
+ * reset, ensuring the custom color persists on both desktop and mobile.
+ */
+export const CustomColorOverride = {
+    parameters: {
+        theme: createTheme({
+            text: {
+                fontFamily: "Arial, sans-serif",
+                fontSize: "16px",
+                color: "#333333",
+            },
+        }),
+    },
+    render: () => (_jsx(MjmlSection, { children: _jsx(MjmlColumn, { children: _jsxs(MjmlText, { children: ["Click", " ", _jsx(HtmlInlineLink, { href: "https://example.com", style: { color: "#0066cc !important" }, children: "here" }), " ", "to continue."] }) }) })),
+};
+export const WithTextVariants = {
+    parameters: {
+        theme: createTheme({
+            text: {
+                fontFamily: "Arial, sans-serif",
+                color: "#333333",
+                variants: {
+                    heading: { fontSize: "32px", fontWeight: 700, lineHeight: "40px" },
+                    body: { fontSize: "16px", lineHeight: "24px" },
+                },
+            },
+        }),
+    },
+    render: () => (_jsx(MjmlSection, { children: _jsxs(MjmlColumn, { children: [_jsxs(MjmlText, { variant: "heading", bottomSpacing: true, children: ["Welcome to ", _jsx(HtmlInlineLink, { href: "https://example.com", children: "our platform" })] }), _jsxs(MjmlText, { variant: "body", children: ["Explore our ", _jsx(HtmlInlineLink, { href: "https://example.com/features", children: "features" }), " and start building today."] })] }) })),
+};

package/lib/components/mailRoot/MjmlMailRoot.js

@@ -16,5 +16,5 @@ import { ThemeProvider } from "../../theme/ThemeProvider.js";
  */
 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 })] }) }));
+    return (_jsx(ThemeProvider, { theme: theme, children: _jsxs(Mjml, { children: [_jsxs(MjmlHead, { children: [_jsx(MjmlAttributes, { children: _jsx(MjmlAll, { padding: "0", fontFamily: theme.text.fontFamily }) }), _jsx(MjmlBreakpoint, { width: `${theme.breakpoints.mobile.value}px` }), _jsx(Styles, {})] }), _jsx(MjmlBody, { width: theme.sizes.bodyWidth, backgroundColor: theme.colors.background.body, children: children })] }) }));
 }

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

@@ -4,3 +4,4 @@ type Story = StoryObj<typeof MjmlMailRoot>;
 declare const config: Meta<typeof MjmlMailRoot>;
 export default config;
 export declare const Basic: Story;
+export declare const CustomBodyBackground: Story;

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

@@ -1,13 +1,18 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { MjmlColumn, MjmlText } from "@faire/mjml-react";
+import { createTheme } from "../../../theme/createTheme.js";
 import { MjmlSection } from "../../section/MjmlSection.js";
 import { MjmlMailRoot } from "../MjmlMailRoot.js";
 const config = {
     title: "Components/MjmlMailRoot",
     component: MjmlMailRoot,
     tags: ["autodocs"],
+    parameters: { mailRoot: false },
 };
 export default config;
 export const Basic = {
-    render: () => (_jsx(MjmlMailRoot, { children: _jsx(MjmlSection, { children: _jsx(MjmlColumn, { children: _jsx(MjmlText, { children: "Hello from MjmlMailRoot" }) }) }) })),
+    render: () => (_jsx(MjmlMailRoot, { children: _jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsx(MjmlText, { children: "Hello from MjmlMailRoot" }) }) }) })),
+};
+export const CustomBodyBackground = {
+    render: () => (_jsx(MjmlMailRoot, { theme: createTheme({ colors: { background: { body: "#EAEAEA" } } }), children: _jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsx(MjmlText, { children: "Custom body background color" }) }) }) })),
 };

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

@@ -12,4 +12,4 @@ export type MjmlSectionProps = IMjmlSectionProps & {
     };
 };
 /** 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;
+export declare function MjmlSection({ children, indent, disableResponsiveBehavior, slotProps, className, ...restProps }: MjmlSectionProps): ReactNode;

package/lib/components/section/MjmlSection.js

@@ -6,11 +6,12 @@ import { getDefaultFromResponsiveValue, getResponsiveOverrides } from "../../the
 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 }) {
+export function MjmlSection({ children, indent, disableResponsiveBehavior, slotProps, className, ...restProps }) {
     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 }) }));
+    const themeBackgroundProps = theme ? { backgroundColor: theme.colors.background.content } : {};
+    return (_jsx(BaseMjmlSection, { className: resolvedClassName, ...themeBackgroundProps, ...indentProps, ...restProps, children: disableResponsiveBehavior ? _jsx(MjmlGroup, { ...slotProps?.group, children: children }) : _jsx(_Fragment, { children: children }) }));
 }
 function getIndentProps(theme) {
     if (theme === null) {

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

@@ -5,4 +5,5 @@ declare const config: Meta<typeof MjmlSection>;
 export default config;
 export declare const Primary: Story;
 export declare const Indented: Story;
+export declare const ExplicitBackgroundColor: Story;
 export declare const DisabledResponsiveBehavior: Story;

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

@@ -16,6 +16,12 @@ export const Indented = {
     },
     render: (args) => (_jsx(MjmlSection, { ...args, children: _jsx(MjmlColumn, { children: _jsx(MjmlText, { children: "Indented section content" }) }) })),
 };
+export const ExplicitBackgroundColor = {
+    args: {
+        backgroundColor: "#FF0000",
+    },
+    render: (args) => (_jsx(MjmlSection, { ...args, children: _jsx(MjmlColumn, { children: _jsx(MjmlText, { children: "Explicit backgroundColor overrides theme default" }) }) })),
+};
 export const DisabledResponsiveBehavior = {
     args: {
         disableResponsiveBehavior: true,

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

@@ -0,0 +1,48 @@
+import { type ComponentPropsWithoutRef, type JSX, type ReactNode, type TdHTMLAttributes } from "react";
+import type { VariantName } from "../../theme/themeTypes.js";
+interface HtmlTextOwnProps {
+    /**
+     * 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 TextVariants { heading: true; body: true }
+     * }
+     * ```
+     *
+     * ```ts
+     * const theme = createTheme({
+     *     text: {
+     *         variants: {
+     *             heading: { fontSize: "24px" },
+     *             body: { fontSize: "16px" },
+     *         },
+     *     },
+     * });
+     */
+    variant?: VariantName;
+    /** When true, applies spacing below the text. */
+    bottomSpacing?: boolean;
+}
+export type HtmlTextProps<E extends keyof JSX.IntrinsicElements = "td"> = HtmlTextOwnProps & {
+    /**
+     * The HTML element to render instead of the default `<td>`.
+     *
+     * @example
+     * ```tsx
+     * <HtmlText element="div">Rendered as a div</HtmlText>
+     * <HtmlText element="a" href="/link">Rendered as an anchor</HtmlText>
+     * ```
+     */
+    element?: E;
+} & Omit<ComponentPropsWithoutRef<E>, keyof HtmlTextOwnProps | "element">;
+/**
+ * Themed text component for use inside MJML ending tags or outside of the MJML context.
+ */
+export declare function HtmlText<E extends keyof JSX.IntrinsicElements>(props: HtmlTextOwnProps & {
+    element: E;
+} & Omit<ComponentPropsWithoutRef<E>, keyof HtmlTextOwnProps | "element">): ReactNode;
+export declare function HtmlText(props: HtmlTextOwnProps & Omit<TdHTMLAttributes<HTMLTableCellElement>, keyof HtmlTextOwnProps>): ReactNode;
+export {};

package/lib/components/text/HtmlText.js

@@ -0,0 +1,47 @@
+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 { useTheme } from "../../theme/ThemeProvider.js";
+import { OutlookTextStyleProvider } from "./OutlookTextStyleContext.js";
+import { generateResponsiveTextCss } from "./textStyles.js";
+export function HtmlText({ element: Element = "td", variant: variantProp, bottomSpacing, className, style, children, ...restProps }) {
+    const theme = useTheme();
+    const { defaultVariant, variants, ...baseStyles } = theme.text;
+    const activeVariant = variantProp ?? defaultVariant;
+    const variantStyles = activeVariant ? variants?.[activeVariant] : undefined;
+    const mergedStyles = variantStyles ? { ...baseStyles, ...variantStyles } : baseStyles;
+    const themeStyle = {
+        fontFamily: getDefaultOrUndefined(mergedStyles.fontFamily),
+        fontSize: getDefaultOrUndefined(mergedStyles.fontSize),
+        fontWeight: getDefaultOrUndefined(mergedStyles.fontWeight),
+        fontStyle: getDefaultOrUndefined(mergedStyles.fontStyle),
+        lineHeight: getDefaultOrUndefined(mergedStyles.lineHeight),
+        letterSpacing: getDefaultOrUndefined(mergedStyles.letterSpacing),
+        textDecoration: getDefaultOrUndefined(mergedStyles.textDecoration),
+        textTransform: getDefaultOrUndefined(mergedStyles.textTransform),
+        color: getDefaultOrUndefined(mergedStyles.color),
+        ...(getDefaultOrUndefined(mergedStyles.lineHeight) !== undefined && { msoLineHeightRule: "exactly" }),
+        ...(bottomSpacing && { paddingBottom: getDefaultOrUndefined(mergedStyles.bottomSpacing) }),
+    };
+    const outlookTextStyleValues = {
+        fontFamily: themeStyle.fontFamily,
+        fontSize: themeStyle.fontSize,
+        lineHeight: themeStyle.lineHeight,
+        fontWeight: themeStyle.fontWeight,
+        color: themeStyle.color,
+        ...(style?.fontFamily !== undefined && { fontFamily: style.fontFamily }),
+        ...(style?.fontSize !== undefined && { fontSize: style.fontSize }),
+        ...(style?.lineHeight !== undefined && { lineHeight: style.lineHeight }),
+        ...(style?.fontWeight !== undefined && { fontWeight: style.fontWeight }),
+        ...(style?.color !== undefined && { color: style.color }),
+    };
+    return (_jsx(Element, { ...restProps, className: clsx("htmlText", activeVariant && `htmlText--${activeVariant}`, bottomSpacing && "htmlText--bottomSpacing", className), style: { ...themeStyle, ...style }, children: _jsx(OutlookTextStyleProvider, { value: outlookTextStyleValues, children: children }) }));
+}
+function generateHtmlTextStyles(theme) {
+    return generateResponsiveTextCss(theme, {
+        styleSelector: (variantName) => `.htmlText--${variantName}`,
+        spacingSelector: (variantName) => `.htmlText--bottomSpacing.htmlText--${variantName}`,
+    });
+}
+registerStyles(generateHtmlTextStyles);

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

@@ -0,0 +1,37 @@
+import { type IMjmlTextProps } from "@faire/mjml-react";
+import type { ReactNode } from "react";
+import type { Theme, VariantName } from "../../theme/themeTypes.js";
+export type MjmlTextProps = IMjmlTextProps & {
+    /**
+     * 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 TextVariants { heading: true; body: true }
+     * }
+     * ```
+     *
+     * ```ts
+     * const theme = createTheme({
+     *     text: {
+     *         variants: {
+     *             heading: { fontSize: "24px" },
+     *             body: { fontSize: "16px" },
+     *         },
+     *     },
+     * });
+     */
+    variant?: VariantName;
+    /** When true, applies spacing below the text. */
+    bottomSpacing?: boolean;
+};
+/**
+ * Text component that can be styled using the theme, optionally using a variant.
+ *
+ * Works without a `ThemeProvider` as a plain pass-through to the base MJML text component.
+ * The `variant` and `bottomSpacing` props require a `ThemeProvider` (or `MjmlMailRoot`).
+ */
+export declare function MjmlText({ variant: variantProp, bottomSpacing, className, children, ...restProps }: MjmlTextProps): ReactNode;
+export declare function generateTextStyles(theme: Theme): string;

package/lib/components/text/MjmlText.js

@@ -0,0 +1,65 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { MjmlText as BaseMjmlText } from "@faire/mjml-react";
+import clsx from "clsx";
+import { registerStyles } from "../../styles/registerStyles.js";
+import { getDefaultOrUndefined } from "../../theme/responsiveValue.js";
+import { useOptionalTheme } from "../../theme/ThemeProvider.js";
+import { OutlookTextStyleProvider } from "./OutlookTextStyleContext.js";
+import { generateResponsiveTextCss } from "./textStyles.js";
+/**
+ * Text component that can be styled using the theme, optionally using a variant.
+ *
+ * Works without a `ThemeProvider` as a plain pass-through to the base MJML text component.
+ * The `variant` and `bottomSpacing` props require a `ThemeProvider` (or `MjmlMailRoot`).
+ */
+export function MjmlText({ variant: variantProp, bottomSpacing, className, children, ...restProps }) {
+    const theme = useOptionalTheme();
+    const themedProps = getThemedProps(theme, variantProp, bottomSpacing, restProps);
+    const resolvedClassName = clsx("mjmlText", themedProps.activeVariant && `mjmlText--${themedProps.activeVariant}`, bottomSpacing && "mjmlText--bottomSpacing", className);
+    return (_jsx(BaseMjmlText, { ...themedProps.baseProps, className: resolvedClassName, ...restProps, children: themedProps.outlookTextStyleValues !== null ? (_jsx(OutlookTextStyleProvider, { value: themedProps.outlookTextStyleValues, children: children })) : (children) }));
+}
+function getThemedProps(theme, variantProp, bottomSpacing, explicitProps) {
+    if (theme === null) {
+        if (variantProp !== undefined) {
+            throw new Error("The `variant` prop requires being wrapped in a ThemeProvider or MjmlMailRoot.");
+        }
+        if (bottomSpacing) {
+            throw new Error("The `bottomSpacing` prop requires being wrapped in a ThemeProvider or MjmlMailRoot.");
+        }
+        return { activeVariant: undefined, baseProps: {}, outlookTextStyleValues: null };
+    }
+    const { defaultVariant, variants, ...baseStyles } = theme.text;
+    const activeVariant = variantProp ?? defaultVariant;
+    const variantStyles = activeVariant ? variants?.[activeVariant] : undefined;
+    const mergedStyles = variantStyles ? { ...baseStyles, ...variantStyles } : baseStyles;
+    const fontWeightDefault = getDefaultOrUndefined(mergedStyles.fontWeight);
+    return {
+        activeVariant,
+        baseProps: {
+            fontFamily: getDefaultOrUndefined(mergedStyles.fontFamily),
+            fontSize: getDefaultOrUndefined(mergedStyles.fontSize),
+            fontWeight: fontWeightDefault !== undefined ? String(fontWeightDefault) : undefined,
+            fontStyle: getDefaultOrUndefined(mergedStyles.fontStyle),
+            lineHeight: getDefaultOrUndefined(mergedStyles.lineHeight),
+            letterSpacing: getDefaultOrUndefined(mergedStyles.letterSpacing),
+            textDecoration: getDefaultOrUndefined(mergedStyles.textDecoration),
+            textTransform: getDefaultOrUndefined(mergedStyles.textTransform),
+            color: getDefaultOrUndefined(mergedStyles.color),
+            paddingBottom: bottomSpacing ? getDefaultOrUndefined(mergedStyles.bottomSpacing) : undefined,
+        },
+        outlookTextStyleValues: {
+            fontFamily: explicitProps.fontFamily ?? getDefaultOrUndefined(mergedStyles.fontFamily),
+            fontSize: explicitProps.fontSize ?? getDefaultOrUndefined(mergedStyles.fontSize),
+            fontWeight: explicitProps.fontWeight ?? fontWeightDefault,
+            lineHeight: explicitProps.lineHeight ?? getDefaultOrUndefined(mergedStyles.lineHeight),
+            color: explicitProps.color ?? getDefaultOrUndefined(mergedStyles.color),
+        },
+    };
+}
+export function generateTextStyles(theme) {
+    return generateResponsiveTextCss(theme, {
+        styleSelector: (variantName) => `.mjmlText--${variantName} > div`,
+        spacingSelector: (variantName) => `.mjmlText--bottomSpacing.mjmlText--${variantName}`,
+    });
+}
+registerStyles(generateTextStyles);

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

@@ -0,0 +1,9 @@
+import { type CSSProperties, type ReactNode } from "react";
+type OutlookTextStyleValues = Pick<CSSProperties, "fontFamily" | "fontSize" | "lineHeight" | "fontWeight" | "color">;
+declare function OutlookTextStyleProvider({ value, children }: {
+    value: OutlookTextStyleValues;
+    children: ReactNode;
+}): ReactNode;
+declare function useOutlookTextStyle(): OutlookTextStyleValues | null;
+export { OutlookTextStyleProvider, useOutlookTextStyle };
+export type { OutlookTextStyleValues };

package/lib/components/text/OutlookTextStyleContext.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const OutlookTextStyleContext = createContext(null);
+function OutlookTextStyleProvider({ value, children }) {
+    return _jsx(OutlookTextStyleContext, { value: value, children: children });
+}
+function useOutlookTextStyle() {
+    return useContext(OutlookTextStyleContext);
+}
+export { OutlookTextStyleProvider, useOutlookTextStyle };

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

@@ -0,0 +1,12 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { HtmlText } from "../HtmlText.js";
+type Story = StoryObj<typeof HtmlText>;
+declare const config: Meta<typeof HtmlText>;
+export default config;
+export declare const Default: Story;
+export declare const WithVariants: Story;
+export declare const ResponsiveVariants: Story;
+export declare const BottomSpacing: Story;
+export declare const DefaultVariant: Story;
+export declare const ElementPropAsDiv: Story;
+export declare const ElementPropAsAnchor: Story;