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

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/__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/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/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.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", 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

@@ -0,0 +1,7 @@
+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;
+export declare const CustomBodyBackground: Story;

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

@@ -0,0 +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, { 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

@@ -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, ...restProps }: MjmlSectionProps): ReactNode;

package/lib/components/section/MjmlSection.js

@@ -0,0 +1,44 @@
+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, ...restProps }) {
+    const theme = useOptionalTheme();
+    const indentProps = indent ? getIndentProps(theme) : {};
+    const resolvedClassName = clsx("mjmlSection", indent && "mjmlSection--indented", className);
+    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) {
+        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,9 @@
+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 ExplicitBackgroundColor: Story;
+export declare const DisabledResponsiveBehavior: Story;

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

@@ -0,0 +1,30 @@
+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 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,
+    },
+    render: (args) => (_jsxs(MjmlSection, { ...args, children: [_jsx(MjmlColumn, { children: _jsx(MjmlText, { children: "First column" }) }), _jsx(MjmlColumn, { children: _jsx(MjmlText, { children: "Second column" }) })] })),
+};

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;