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

package/README.md

@@ -38,7 +38,10 @@ Themed components expose their styling through the theme: a flat base entry and
 - **Location.** Custom components live in `src/components/<concern>/` (e.g. `src/components/section/MjmlSection.tsx`).
 - **File order.** Imports → types/props → component → styles. `registerStyles` calls go below the component.
 - **Module format.** ESM only (`type: module`). Use `.js` extensions in imports.
-- **TSDoc.** Short TSDoc — one line where possible — on exported components and props.
+- **TSDoc.** Short — one line where possible — on exported components and props.
+- **Prop defaults.** Add `@defaultValue` when the default isn't obvious from the type — runtime defaults, and theme-derived ones the consumer can't see in the shipped types.
+- **Phrasing a default.** Name where the value comes from, not the value itself. One theme token: name it in backticks, as in "The theme's `colors.background.content`". Computed from several: name what it depends on, as in "The theme's `divider` height for the active variant".
+- **Defaults on inherited props.** Redeclare the prop locally (`Omit` it from the base, re-add it with the same type) so the tag is on the prop itself. Never document the default in the component's TSDoc.
 
 ### Storybook
 
@@ -97,9 +100,13 @@ Other sections should be rare — only when content is durable, feature-specific
 
 Feature READMEs (this one included) should stay current. Update them in the same PR as any change that makes them inaccurate or adds context worth recording.
 
-## Consumer-facing documentation
+## Usage documentation
 
-- Docs: [docs/docs/3-features-modules/13-building-html-emails/](../../docs/docs/3-features-modules/13-building-html-emails/)
-- Agent skill: [skills/comet-mail-react/SKILL.md](../../skills/comet-mail-react/SKILL.md)
+Two artifacts document how to _use_ this package, for two readers:
 
-When a change here affects usage patterns, component APIs, or styling conventions, update these alongside the library change.
+- **Docs** — [docs/docs/3-features-modules/13-building-html-emails/](../../docs/docs/3-features-modules/13-building-html-emails/) — for people building emails with the package.
+- **Agent skill** — [skills/comet-mail-react/SKILL.md](../../skills/comet-mail-react/SKILL.md) — the same guidance for AI agents working in a project that uses this package.
+
+Both teach the same things: what the package is for, how to build emails with it, the patterns to reach for, and the email-client pitfalls — markup that's fine in a browser can render wrong in clients like Outlook. They differ in one respect — an agent already has the package's types and TSDoc in its project, so the skill doesn't restate type signatures, prop lists, or defaults; those live in the types and TSDoc, and it spends its words on everything they can't convey on their own.
+
+When a change affects how the package is used — components added/removed/renamed, changed behavior, new usage patterns, or styling conventions — update both in the same PR; consider a separate docs commit so reviewers can take them on their own.

package/lib/blocks.generated.d.ts

@@ -54,6 +54,7 @@ export interface EmailLinkBlockData {
 export interface ExternalLinkBlockData {
     targetUrl?: string;
     openInNewWindow: boolean;
+    noFollow: boolean;
 }
 export interface InternalLinkBlockData {
     targetPageAnchor?: string;

package/lib/components/button/HtmlButton.d.ts

@@ -0,0 +1,9 @@
+import type { AnchorHTMLAttributes, ReactNode } from "react";
+import type { Theme } from "../../theme/themeTypes.js";
+import type { ButtonProps } from "./buttonProps.js";
+export type HtmlButtonProps = ButtonProps & Omit<AnchorHTMLAttributes<HTMLAnchorElement>, keyof ButtonProps>;
+/**
+ * Themed button for use inside MJML ending tags or outside of the MJML context.
+ */
+export declare function HtmlButton({ variant: variantProp, fullWidth, target, href, className, style, children, ...restProps }: HtmlButtonProps): ReactNode;
+export declare function generateHtmlButtonStyles(theme: Theme): string;

package/lib/components/button/HtmlButton.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import clsx from "clsx";
+import { registerStyles } from "../../styles/registerStyles.js";
+import { defaultTheme } from "../../theme/defaultTheme.js";
+import { getDefaultOrUndefined } from "../../theme/responsiveValue.js";
+import { useOptionalTheme } from "../../theme/ThemeProvider.js";
+import { defaultButtonStyles } from "./defaultButtonStyles.js";
+import { generateResponsiveButtonCss } from "./generateResponsiveButtonCss.js";
+/**
+ * Themed button for use inside MJML ending tags or outside of the MJML context.
+ */
+export function HtmlButton({ variant: variantProp, fullWidth, target = "_blank", href = "#", className, style, children, ...restProps }) {
+    const theme = useOptionalTheme();
+    if (theme === null && variantProp !== undefined) {
+        throw new Error("The `variant` prop requires being wrapped in a ThemeProvider or MjmlMailRoot.");
+    }
+    const themeButton = theme?.button ?? defaultButtonStyles;
+    const textStyles = theme?.text ?? defaultTheme.text;
+    const { defaultVariant, variants, ...baseStyles } = themeButton;
+    const activeVariant = variantProp ?? defaultVariant;
+    const variantStyles = activeVariant ? variants?.[activeVariant] : undefined;
+    const mergedStyles = { ...baseStyles, ...variantStyles };
+    const backgroundColor = getDefaultOrUndefined(mergedStyles.backgroundColor);
+    const borderRadius = getDefaultOrUndefined(mergedStyles.borderRadius);
+    const innerPadding = getDefaultOrUndefined(mergedStyles.padding);
+    const cellStyle = {
+        border: getDefaultOrUndefined(mergedStyles.border),
+        borderRadius,
+        backgroundColor,
+        msoPaddingAlt: innerPadding,
+    };
+    const anchorStyle = {
+        display: fullWidth ? "block" : "inline-block",
+        boxSizing: fullWidth ? "border-box" : undefined,
+        width: fullWidth ? "100%" : undefined,
+        backgroundColor,
+        backgroundImage: getDefaultOrUndefined(mergedStyles.backgroundImage),
+        color: getDefaultOrUndefined(mergedStyles.color),
+        fontFamily: getDefaultOrUndefined(mergedStyles.fontFamily) ?? textStyles.fontFamily,
+        fontSize: getDefaultOrUndefined(mergedStyles.fontSize) ?? textStyles.fontSize,
+        fontWeight: getDefaultOrUndefined(mergedStyles.fontWeight) ?? textStyles.fontWeight,
+        lineHeight: getDefaultOrUndefined(mergedStyles.lineHeight) ?? textStyles.lineHeight,
+        margin: 0,
+        textAlign: "center",
+        textDecoration: "none",
+        padding: innerPadding,
+        borderRadius,
+        msoPaddingAlt: "0px",
+        ...style,
+    };
+    return (_jsx("table", { role: "presentation", cellPadding: 0, cellSpacing: 0, border: 0, width: fullWidth ? "100%" : undefined, className: clsx("htmlButton", activeVariant && `htmlButton--${activeVariant}`, fullWidth && "htmlButton--fullWidth", className), style: { borderCollapse: "separate", lineHeight: "100%", msoLineHeightRule: "exactly" }, children: _jsx("tbody", { children: _jsx("tr", { children: _jsx("td", { align: "center", valign: "middle", bgcolor: backgroundColor, style: cellStyle, children: _jsx("a", { ...restProps, href: href, target: target, style: anchorStyle, children: children }) }) }) }) }));
+}
+export function generateHtmlButtonStyles(theme) {
+    return generateResponsiveButtonCss(theme, {
+        styleSelector: (variantName) => `.htmlButton--${variantName} a`,
+    });
+}
+registerStyles(generateHtmlButtonStyles);

package/lib/components/button/MjmlButton.d.ts

@@ -0,0 +1,10 @@
+import { type IMjmlButtonProps } from "@faire/mjml-react";
+import type { ReactNode } from "react";
+import type { Theme } from "../../theme/themeTypes.js";
+import type { ButtonProps } from "./buttonProps.js";
+export type MjmlButtonProps = Omit<IMjmlButtonProps, "href" | "target"> & ButtonProps;
+/**
+ * Themed button for use inside an `MjmlColumn`.
+ */
+export declare function MjmlButton({ variant: variantProp, fullWidth, width, href, target, className, children, ...restProps }: MjmlButtonProps): ReactNode;
+export declare function generateMjmlButtonStyles(theme: Theme): string;

package/lib/components/button/MjmlButton.js

@@ -0,0 +1,91 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { MjmlButton as BaseMjmlButton } 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 { css } from "../../utils/css.js";
+import { defaultButtonStyles } from "./defaultButtonStyles.js";
+import { generateResponsiveButtonCss } from "./generateResponsiveButtonCss.js";
+/**
+ * Themed button for use inside an `MjmlColumn`.
+ */
+export function MjmlButton({ variant: variantProp, fullWidth, width, href = "#", target = "_blank", className, children, ...restProps }) {
+    const theme = useOptionalTheme();
+    const themedProps = getThemedProps(theme, variantProp);
+    return (_jsx(BaseMjmlButton, { ...themedProps.baseProps, ...restProps, href: href, target: target, width: fullWidth ? "100%" : width, className: clsx("mjmlButton", themedProps.activeVariant && `mjmlButton--${themedProps.activeVariant}`, fullWidth && "mjmlButton--fullWidth", className), children: children }));
+}
+function getThemedProps(theme, variantProp) {
+    if (theme === null && variantProp !== undefined) {
+        throw new Error("The `variant` prop requires being wrapped in a ThemeProvider or MjmlMailRoot.");
+    }
+    const themeButton = theme?.button ?? defaultButtonStyles;
+    const { defaultVariant, variants, ...baseStyles } = themeButton;
+    const activeVariant = variantProp ?? defaultVariant;
+    const variantStyles = activeVariant ? variants?.[activeVariant] : undefined;
+    const mergedStyles = { ...baseStyles, ...variantStyles };
+    const fontWeightDefault = getDefaultOrUndefined(mergedStyles.fontWeight);
+    return {
+        activeVariant,
+        baseProps: {
+            color: getDefaultOrUndefined(mergedStyles.color),
+            backgroundColor: getDefaultOrUndefined(mergedStyles.backgroundColor),
+            border: getDefaultOrUndefined(mergedStyles.border),
+            borderRadius: getDefaultOrUndefined(mergedStyles.borderRadius),
+            fontFamily: getDefaultOrUndefined(mergedStyles.fontFamily),
+            fontSize: getDefaultOrUndefined(mergedStyles.fontSize),
+            fontWeight: fontWeightDefault !== undefined ? String(fontWeightDefault) : undefined,
+            lineHeight: getDefaultOrUndefined(mergedStyles.lineHeight),
+            innerPadding: getDefaultOrUndefined(mergedStyles.padding),
+        },
+    };
+}
+// The wrapped MJML button has no `background-image` prop, so a gradient goes in a `<style>`
+// rule over the solid `backgroundColor`; variant rules come after the base so they override it.
+// Only the static value lives here; responsive overrides flow through generateResponsiveButtonCss.
+function generateStaticBackgroundImageCss(theme) {
+    const { variants, ...baseStyles } = theme.button;
+    const cssChunks = [];
+    const baseBackgroundImage = getDefaultOrUndefined(baseStyles.backgroundImage);
+    if (baseBackgroundImage !== undefined) {
+        cssChunks.push(css `
+            .mjmlButton a {
+                background-image: ${baseBackgroundImage} !important;
+            }
+        `);
+    }
+    if (variants) {
+        for (const [variantName, variantStyles] of Object.entries(variants)) {
+            const backgroundImage = getDefaultOrUndefined(variantStyles?.backgroundImage);
+            if (backgroundImage !== undefined) {
+                cssChunks.push(css `
+                    .mjmlButton--${variantName} a {
+                        background-image: ${backgroundImage} !important;
+                    }
+                `);
+            }
+        }
+    }
+    return cssChunks.join("\n");
+}
+export function generateMjmlButtonStyles(theme) {
+    return [
+        generateStaticBackgroundImageCss(theme),
+        generateResponsiveButtonCss(theme, {
+            styleSelector: (variantName) => `.mjmlButton--${variantName} a`,
+        }),
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+registerStyles(generateMjmlButtonStyles);
+// The cell is already full-width; this widens the anchor inside it so a gradient covers the
+// whole bar and the whole bar is clickable. Inlined so it survives clients that drop `<style>`.
+registerStyles(css `
+        .mjmlButton--fullWidth a {
+            display: block !important;
+            width: 100% !important;
+            box-sizing: border-box !important;
+            text-align: center !important;
+        }
+    `, { inline: true });

package/lib/components/button/buttonProps.d.ts

@@ -0,0 +1,35 @@
+import type { AnchorHTMLAttributes } from "react";
+import type { ButtonVariantName } from "../../theme/themeTypes.js";
+export interface ButtonProps {
+    /**
+     * 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 ButtonVariants { primary: true; secondary: true }
+     * }
+     * ```
+     *
+     * ```ts
+     * const theme = createTheme({
+     *     button: {
+     *         variants: {
+     *             primary: { backgroundColor: "#5B4FC7", color: "#FFFFFF" },
+     *             secondary: { backgroundColor: "#EEEEEE", color: "#222222" },
+     *         },
+     *     },
+     * });
+     * ```
+     *
+     * @defaultValue The theme's `button.defaultVariant`, when set
+     */
+    variant?: ButtonVariantName;
+    /** When true, the button spans the full width of its container. */
+    fullWidth?: boolean;
+    /** @defaultValue "#" */
+    href?: string;
+    /** @defaultValue "_blank" */
+    target?: AnchorHTMLAttributes<HTMLAnchorElement>["target"];
+}

package/lib/components/button/defaultButtonStyles.d.ts

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

package/lib/components/button/defaultButtonStyles.js

@@ -0,0 +1,9 @@
+export const defaultButtonStyles = {
+    color: "#ffffff",
+    backgroundColor: "#414141",
+    border: "none",
+    borderRadius: "3px",
+    fontSize: "13px",
+    lineHeight: "120%",
+    padding: "10px 25px",
+};

package/lib/components/button/generateResponsiveButtonCss.d.ts

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

package/lib/components/button/generateResponsiveButtonCss.js

@@ -0,0 +1,21 @@
+import { generateResponsiveVariantCss } from "../../styles/generateResponsiveVariantCss.js";
+const buttonProperties = [
+    "color",
+    "backgroundColor",
+    "backgroundImage",
+    "border",
+    "borderRadius",
+    "fontFamily",
+    "fontSize",
+    "fontWeight",
+    "lineHeight",
+    "padding",
+];
+/** Generates responsive CSS media queries for button variant overrides. */
+export function generateResponsiveButtonCss(theme, options) {
+    return generateResponsiveVariantCss({
+        breakpoints: theme.breakpoints,
+        variants: theme.button.variants,
+        groups: [{ selector: options.styleSelector, properties: buttonProperties }],
+    });
+}

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

@@ -2,7 +2,8 @@ import type { CSSProperties } from "react";
 import type { DividerVariantName } from "../../theme/themeTypes.js";
 export interface DividerProps {
     /**
-     * The component's variant to apply, as defined in the theme.
+     * The component's variant to apply, as defined in the theme. Requires a
+     * theme (`ThemeProvider` or `MjmlMailRoot`) when set.
      *
      * Custom variants should be defined in the theme through module augmentation:
      *
@@ -22,15 +23,27 @@ export interface DividerProps {
      *     },
      * });
      * ```
+     *
+     * @defaultValue The theme's `divider.defaultVariant`, when set
      */
     variant?: DividerVariantName;
-    /** Height of the divider in pixels. */
+    /**
+     * Height of the divider in pixels.
+     *
+     * @defaultValue The theme's `divider` height for the active variant
+     */
     height?: number;
-    /** Background color of the divider (e.g. `"#FF0000"`). */
+    /**
+     * Background color of the divider (e.g. `"#FF0000"`).
+     *
+     * @defaultValue The theme's `divider` background color for the active variant
+     */
     backgroundColor?: string;
     /**
      * Background image for the divider — typically a gradient. Clients that
      * don't render `background-image` fall back to the solid `backgroundColor`.
+     *
+     * @defaultValue The theme's `divider` background image for the active variant
      */
     backgroundImage?: string;
     className?: string;

package/lib/components/divider/generateResponsiveDividerCss.js

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

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

@@ -1,5 +1,12 @@
 import type { ComponentProps, ReactNode } from "react";
-export type HtmlInlineLinkProps = ComponentProps<"a">;
+export type HtmlInlineLinkProps = Omit<ComponentProps<"a">, "target"> & {
+    /**
+     * Where to open the linked document.
+     *
+     * @defaultValue `"_blank"`
+     */
+    target?: ComponentProps<"a">["target"];
+};
 /**
  * Inline link styled to match the surrounding text, for use inside `HtmlText` or `MjmlText`.
  *

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

@@ -3,8 +3,9 @@ import { type Config } from "../../config/ConfigProvider.js";
 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 to use for the email.
+     *
+     * @defaultValue `createTheme()`
      */
     theme?: Theme;
     /** Extra content appended inside the built-in `<MjmlAttributes>`, after the default `<MjmlAll>`. */

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

@@ -1,6 +1,12 @@
 import { type IMjmlGroupProps, type IMjmlSectionProps } from "@faire/mjml-react";
 import type { ReactNode } from "react";
-export type MjmlSectionProps = IMjmlSectionProps & {
+export type MjmlSectionProps = Omit<IMjmlSectionProps, "backgroundColor"> & {
+    /**
+     * Background color of the section.
+     *
+     * @defaultValue The theme's `colors.background.content`, unless inside an `MjmlWrapper`
+     */
+    backgroundColor?: IMjmlSectionProps["backgroundColor"];
     /** Applies theme-based content indentation with responsive overrides. */
     indent?: boolean;
     /** When true, child columns remain side-by-side on mobile instead of stacking vertically. */

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

@@ -21,6 +21,9 @@ interface HtmlTextOwnProps {
      *         },
      *     },
      * });
+     * ```
+     *
+     * @defaultValue The theme's `text.defaultVariant`, when set
      */
     variant?: VariantName;
     /** When true, applies spacing below the text. */

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

@@ -22,6 +22,9 @@ export type MjmlTextProps = IMjmlTextProps & {
      *         },
      *     },
      * });
+     * ```
+     *
+     * @defaultValue The theme's `text.defaultVariant`, when set
      */
     variant?: VariantName;
     /** When true, applies spacing below the text. */

package/lib/components/text/textStyles.js

@@ -1,74 +1,24 @@
-import { getResponsiveOverrides } from "../../theme/responsiveValue.js";
-import { css } from "../../utils/css.js";
-const textStyleCssProperties = [
-    ["fontFamily", "font-family"],
-    ["fontSize", "font-size"],
-    ["fontWeight", "font-weight"],
-    ["fontStyle", "font-style"],
-    ["lineHeight", "line-height"],
-    ["letterSpacing", "letter-spacing"],
-    ["textDecoration", "text-decoration"],
-    ["textTransform", "text-transform"],
-    ["color", "color"],
+import { generateResponsiveVariantCss } from "../../styles/generateResponsiveVariantCss.js";
+const textStyleProperties = [
+    "fontFamily",
+    "fontSize",
+    "fontWeight",
+    "fontStyle",
+    "lineHeight",
+    "letterSpacing",
+    "textDecoration",
+    "textTransform",
+    "color",
 ];
+const spacingProperties = [{ themeKey: "bottomSpacing", cssProperties: "padding-bottom" }];
 /** Generates responsive CSS media queries for text variant overrides. */
 export function generateResponsiveTextCss(theme, options) {
-    const { variants } = theme.text;
-    if (!variants) {
-        return css ``;
-    }
-    const cssChunks = [];
-    for (const [variantName, variantStyles] of Object.entries(variants)) {
-        if (!variantStyles) {
-            continue;
-        }
-        const styleOverrides = new Map();
-        const spacingOverrides = new Map();
-        for (const [themeKey, cssProperty] of textStyleCssProperties) {
-            const value = variantStyles[themeKey];
-            if (value === undefined) {
-                continue;
-            }
-            for (const { breakpointKey, value: breakpointValue } of getResponsiveOverrides(value)) {
-                const declarations = styleOverrides.get(breakpointKey) ?? [];
-                declarations.push(`${cssProperty}: ${String(breakpointValue)} !important`);
-                styleOverrides.set(breakpointKey, declarations);
-            }
-        }
-        const bottomSpacingValue = variantStyles.bottomSpacing;
-        if (bottomSpacingValue !== undefined) {
-            for (const { breakpointKey, value: breakpointValue } of getResponsiveOverrides(bottomSpacingValue)) {
-                const declarations = spacingOverrides.get(breakpointKey) ?? [];
-                declarations.push(`padding-bottom: ${String(breakpointValue)} !important`);
-                spacingOverrides.set(breakpointKey, declarations);
-            }
-        }
-        for (const [breakpointKey, declarations] of styleOverrides) {
-            const breakpoint = theme.breakpoints[breakpointKey];
-            if (!breakpoint) {
-                continue;
-            }
-            cssChunks.push(css `
-                ${breakpoint.belowMediaQuery} {
-                    ${options.styleSelector(variantName)} {
-                        ${declarations.join(";\n")}
-                    }
-                }
-            `);
-        }
-        for (const [breakpointKey, declarations] of spacingOverrides) {
-            const breakpoint = theme.breakpoints[breakpointKey];
-            if (!breakpoint) {
-                continue;
-            }
-            cssChunks.push(css `
-                ${breakpoint.belowMediaQuery} {
-                    ${options.spacingSelector(variantName)} {
-                        ${declarations.join(";\n")}
-                    }
-                }
-            `);
-        }
-    }
-    return cssChunks.join("\n");
+    return generateResponsiveVariantCss({
+        breakpoints: theme.breakpoints,
+        variants: theme.text.variants,
+        groups: [
+            { selector: options.styleSelector, properties: textStyleProperties },
+            { selector: options.spacingSelector, properties: spacingProperties },
+        ],
+    });
 }

package/lib/components/wrapper/MjmlWrapper.d.ts

@@ -1,7 +1,14 @@
 import { type IMjmlWrapperProps } from "@faire/mjml-react";
 import type { ReactNode } from "react";
-export type MjmlWrapperProps = IMjmlWrapperProps;
+export type MjmlWrapperProps = Omit<IMjmlWrapperProps, "backgroundColor"> & {
+    /**
+     * Background color of the wrapper.
+     *
+     * @defaultValue The theme's `colors.background.content`
+     */
+    backgroundColor?: IMjmlWrapperProps["backgroundColor"];
+};
 /**
- * A wrapper that groups multiple sections sharing a background. Must be a direct child of MjmlBody.
+ * A wrapper that groups multiple sections sharing a background. Must be a direct child of `MjmlBody`.
  */
 export declare function MjmlWrapper({ children, ...restProps }: MjmlWrapperProps): ReactNode;

package/lib/components/wrapper/MjmlWrapper.js

@@ -3,7 +3,7 @@ import { MjmlWrapper as BaseMjmlWrapper } from "@faire/mjml-react";
 import { useOptionalTheme } from "../../theme/ThemeProvider.js";
 import { InsideMjmlWrapperContext } from "./InsideMjmlWrapperContext.js";
 /**
- * A wrapper that groups multiple sections sharing a background. Must be a direct child of MjmlBody.
+ * A wrapper that groups multiple sections sharing a background. Must be a direct child of `MjmlBody`.
  */
 export function MjmlWrapper({ children, ...restProps }) {
     const theme = useOptionalTheme();

package/lib/index.d.ts

@@ -8,6 +8,10 @@ export type { HtmlPixelImageBlockProps } from "./blocks/pixelImage/HtmlPixelImag
 export { HtmlPixelImageBlock } from "./blocks/pixelImage/HtmlPixelImageBlock.js";
 export type { MjmlPixelImageBlockProps } from "./blocks/pixelImage/MjmlPixelImageBlock.js";
 export { MjmlPixelImageBlock } from "./blocks/pixelImage/MjmlPixelImageBlock.js";
+export type { HtmlButtonProps } from "./components/button/HtmlButton.js";
+export { HtmlButton } from "./components/button/HtmlButton.js";
+export type { MjmlButtonProps } from "./components/button/MjmlButton.js";
+export { MjmlButton } from "./components/button/MjmlButton.js";
 export type { HtmlDividerProps } from "./components/divider/HtmlDivider.js";
 export { HtmlDivider } from "./components/divider/HtmlDivider.js";
 export type { MjmlDividerProps } from "./components/divider/MjmlDivider.js";
@@ -34,8 +38,8 @@ 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 { DividerStyles, DividerVariants, DividerVariantStyles, TextStyles, TextVariants, TextVariantStyles, Theme, ThemeBackgroundColors, ThemeBreakpoint, ThemeBreakpoints, ThemeColors, ThemeDivider, ThemeSizes, ThemeText, } from "./theme/themeTypes.js";
+export type { ButtonStyles, ButtonVariants, ButtonVariantStyles, DividerStyles, DividerVariants, DividerVariantStyles, TextStyles, TextVariants, TextVariantStyles, Theme, ThemeBackgroundColors, ThemeBreakpoint, ThemeBreakpoints, ThemeButton, ThemeColors, ThemeDivider, ThemeSizes, ThemeText, } from "./theme/themeTypes.js";
 export { css } from "./utils/css.js";
-export { Mjml, MjmlAccordion, MjmlAccordionElement, type IMjmlAccordionElementProps as MjmlAccordionElementProps, type IMjmlAccordionProps as MjmlAccordionProps, MjmlAccordionText, type IMjmlAccordionTextProps as MjmlAccordionTextProps, MjmlAccordionTitle, type IMjmlAccordionTitleProps as MjmlAccordionTitleProps, MjmlAll, type IMjmlAllProps as MjmlAllProps, MjmlAttributes, type IMjmlAttributesProps as MjmlAttributesProps, MjmlBody, type IMjmlBodyProps as MjmlBodyProps, MjmlBreakpoint, type IMjmlBreakpointProps as MjmlBreakpointProps, MjmlButton, type IMjmlButtonProps as MjmlButtonProps, MjmlCarousel, MjmlCarouselImage, type IMjmlCarouselImageProps as MjmlCarouselImageProps, type IMjmlCarouselProps as MjmlCarouselProps, MjmlClass, type IMjmlClassProps as MjmlClassProps, MjmlColumn, type IMjmlColumnProps as MjmlColumnProps, 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, MjmlInclude, type IMjmlIncludeProps as MjmlIncludeProps, MjmlNavbar, MjmlNavbarLink, type IMjmlNavbarLinkProps as MjmlNavbarLinkProps, type IMjmlNavbarProps as MjmlNavbarProps, MjmlPreview, type IMjmlPreviewProps as MjmlPreviewProps, type IMjmlProps as MjmlProps, MjmlRaw, type IMjmlRawProps as MjmlRawProps, MjmlSelector, type IMjmlSelectorProps as MjmlSelectorProps, MjmlSocial, MjmlSocialElement, type IMjmlSocialElementProps as MjmlSocialElementProps, type IMjmlSocialProps as MjmlSocialProps, MjmlSpacer, type IMjmlSpacerProps as MjmlSpacerProps, MjmlStyle, type IMjmlStyleProps as MjmlStyleProps, MjmlTable, type IMjmlTableProps as MjmlTableProps, MjmlTitle, type IMjmlTitleProps as MjmlTitleProps, } 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, MjmlCarousel, MjmlCarouselImage, type IMjmlCarouselImageProps as MjmlCarouselImageProps, type IMjmlCarouselProps as MjmlCarouselProps, MjmlClass, type IMjmlClassProps as MjmlClassProps, MjmlColumn, type IMjmlColumnProps as MjmlColumnProps, 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, MjmlInclude, type IMjmlIncludeProps as MjmlIncludeProps, MjmlNavbar, MjmlNavbarLink, type IMjmlNavbarLinkProps as MjmlNavbarLinkProps, type IMjmlNavbarProps as MjmlNavbarProps, MjmlPreview, type IMjmlPreviewProps as MjmlPreviewProps, type IMjmlProps as MjmlProps, MjmlRaw, type IMjmlRawProps as MjmlRawProps, MjmlSelector, type IMjmlSelectorProps as MjmlSelectorProps, MjmlSocial, MjmlSocialElement, type IMjmlSocialElementProps as MjmlSocialElementProps, type IMjmlSocialProps as MjmlSocialProps, MjmlSpacer, type IMjmlSpacerProps as MjmlSpacerProps, MjmlStyle, type IMjmlStyleProps as MjmlStyleProps, MjmlTable, type IMjmlTableProps as MjmlTableProps, MjmlTitle, type IMjmlTitleProps as MjmlTitleProps, } 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";