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

package/README.md

@@ -17,6 +17,7 @@ We extend `@faire/mjml-react` rather than fork it. A few rules keep that working
 - **Additive only.** A custom component must work everywhere the base did. Only add props — never remove or rename them, and don't require new providers or context. For theme access, prefer `useOptionalTheme()` over `useTheme()`.
 - **Wrap, don't reimplement.** Custom components delegate to `@faire/mjml-react`. Less to maintain, and we stay close to upstream behaviour.
 - **One export per name.** When we ship a custom version, it replaces the re-export. Consumers should never need to import from `@faire/mjml-react` directly.
+- **Public-facing documentation doesn't reference `@faire/mjml-react`.** TSDoc, story descriptions, and changeset entries describe behavior in terms of this package only. Internal places (feature READMEs, commit messages) can mention upstream when it adds maintainer context.
 
 ### Styling
 
@@ -24,30 +25,88 @@ We extend `@faire/mjml-react` rather than fork it. A few rules keep that working
 - **Media queries** via `registerStyles` are progressive enhancement for mobile, where modern CSS (flex, grid) is fine. Use `theme.breakpoints.*.belowMediaQuery` (max-width queries) to target viewports below a breakpoint.
 - **BEM, camelCase blocks.** Block `mjmlSection`, element `mjmlSection__item`, modifier `mjmlSection--indented`. Every component applies its block class and merges any consumer-provided `className` with `clsx`: `clsx("mjmlSection", className)`.
 
+### Theme variants
+
+Themed components expose their styling through the theme: a flat base entry and an optional, consumer-extensible variants map.
+
+- **Base theme entry covers the unstyled use.** Components render from `theme.<component>` when no variant is picked. The `variant` prop is optional; the package ships no built-in variants.
+- **Variants are declared by the consumer.** Variant names are added via TypeScript module augmentation against the variant-name type for that component. A `defaultVariant` on the theme entry makes one of them the implicit pick.
+- **Responsive values appear only inside variants.** Base entries use plain types per property. Variant entries can declare a `ResponsiveValue<T>` — a `{ default, ...overrides }` shape with override keys drawn from `theme.breakpoints`.
+
 ### File layout
 
 - **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
 
 Every custom component has a story in `src/components/<concern>/__stories__/<Component>.stories.tsx`. Wrap non-section stories in `<MjmlSection indent>` to show a realistic indented layout.
 
-### Changesets
+Placeholder images use the `picsum.photos` seed URL pattern — `https://picsum.photos/seed/<seed>/<width>/<height>` — so the same seed renders the same image on every build.
 
-A changeset describes what changes for the consumer. If the public API and end-user behavior are unchanged, no changeset is needed.
+### Changesets
 
 When a custom component replaces a re-export, describe the change against the previous re-export — the added props, features, or behavior. Consumers don't need to know the internal component is new; they only see what's different in the API they use.
 
-## Living document
+## Internal documentation per feature
+
+Features substantial enough to live in their own directory should have a `README.md` that describes the current state and how the feature changes it — and, when a maintainer might assume otherwise, the boundaries it deliberately doesn't cross. These READMEs are internal — written for the people (and agents) maintaining the code, not for consumers. End-user usage docs live elsewhere (see [Consumer-facing documentation](#consumer-facing-documentation)).
+
+### What is a feature
+
+A feature is any self-contained unit of behavior worth describing on its own — a component (`InlineLink`), a utility (`css` helper), an addon (the Storybook addon), or the package itself. Features nest: this README documents `@comet/mail-react` as a feature, and the components inside it are features in their own right.
+
+A feature README describes **only its own feature**. It does not describe parent features that contain it, nor sub-features it contains — each of those has its own README.
+
+### Where they live
+
+A feature that warrants a README is organized as a directory, with the README at the directory root (e.g. `src/components/inline-link/README.md`). Small features that live as a single file inside a parent don't need their own README — they're just part of the parent. Promote a file to a directory at the same time you give it a README.
+
+### What goes in a feature README
+
+**Title.** Use the exact identifier when the feature is a single component or function (e.g. `MjmlSection`); otherwise use a sentence-case name (e.g. _Inline link_).
+
+Two sections, in order. Only the intro is required.
+
+1. **Intro.** One short paragraph: the current state, and how the feature changes it. Describe the current state as plain facts — what's there, what's required, what's missing — rather than framing it as "a problem the feature solves". Maintainers read this to work on the code, not to be sold on the feature's existence.
+2. **Non-goals** (optional). Things the feature deliberately doesn't do — only when a reader would reasonably assume it does, typically because the feature's name, its domain, or a sibling feature suggests so. The test: would a maintainer look here for this and be surprised it's missing? If not, leave it out. Skip the obvious; skip future work; skip rejected alternatives — those belong in the commit that made the choice.
+
+    Write each bullet as a noun phrase naming the thing not done (`Not a heading component`, `No CSS variables`). Add a single follow-up sentence only when the reader needs to be redirected to the alternative or told why.
+
+Other sections should be rare — only when content is durable, feature-specific, and doesn't fit the two above. Specifically not warranted: no Architecture (the code shows it), no Design decisions (commits carry them), no Usage (consumer docs), no Dependencies (imports show them; non-obvious cross-feature coupling belongs in the intro).
+
+**Express the rule, not the code.** Every line should say something the code doesn't. Don't restate type signatures, prop lists, formulas, or control flow — the code already shows those.
+
+**Length.** Simple feature → one paragraph. Complex feature → one screen, no scrolling. Past a screen and you're probably duplicating commit history or describing what the code shows.
+
+### Template
+
+```md
+# <feature-name>
+
+<One short paragraph: the current state, and how the feature changes it.>
+
+## Non-goals <!-- only if any -->
+
+- <Noun phrase naming what the feature deliberately doesn't do.> <Optional follow-up sentence pointing to the alternative or stating the rationale.>
+```
+
+### Living documents
+
+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.
+
+## Usage documentation
 
-If a change reverses a decision or shifts a convention recorded here, update this README in the same PR.
+Two artifacts document how to _use_ this package, for two readers:
 
-## Consumer-facing companions
+- **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.
 
-- 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)
+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 here affects usage patterns, component APIs, or styling conventions, update these alongside the library change.
+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/pixelImage/HtmlPixelImageBlock.js

@@ -1,7 +1,6 @@
 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 { HtmlImage } from "../../components/image/HtmlImage.js";
 import { usePixelImageBlockData } from "./usePixelImageBlockData.js";
 /**
  * Renders a pixel-image from the DAM as a raw `<img>` tag.
@@ -15,13 +14,5 @@ export function HtmlPixelImageBlock({ data, width, largestPossibleRenderWidth, a
     if (!imageData) {
         return null;
     }
-    return (_jsx("img", { src: imageData.imageUrl, width: imageData.defaultRenderWidth, height: imageData.desktopImageHeight, alt: imageData.alt, title: imageData.title, className: clsx("htmlPixelImageBlock", className), ...imgProps }));
+    return (_jsx(HtmlImage, { src: imageData.imageUrl, width: imageData.defaultRenderWidth, height: imageData.desktopImageHeight, alt: imageData.alt, title: imageData.title, className: clsx("htmlPixelImageBlock", className), ...imgProps }));
 }
-registerStyles((theme) => css `
-        ${theme.breakpoints.default.belowMediaQuery} {
-            .htmlPixelImageBlock {
-                width: 100%;
-                height: auto;
-            }
-        }
-    `);

package/lib/blocks/pixelImage/MjmlPixelImageBlock.d.ts

@@ -1,7 +1,7 @@
-import { type IMjmlImageProps } from "@faire/mjml-react";
 import type { ReactNode } from "react";
+import { type MjmlImageProps } from "../../components/image/MjmlImage.js";
 import type { PixelImageBlockBaseProps } from "./common.js";
-export type MjmlPixelImageBlockProps = Omit<IMjmlImageProps, "src" | "width" | "height"> & PixelImageBlockBaseProps;
+export type MjmlPixelImageBlockProps = Omit<MjmlImageProps, "src" | "width" | "height"> & PixelImageBlockBaseProps;
 /**
  * Renders a pixel-image from the DAM as `MjmlImage`. Must be placed within an
  * `MjmlColumn`. For raw HTML context, use `HtmlPixelImageBlock`.

package/lib/blocks/pixelImage/MjmlPixelImageBlock.js

@@ -1,8 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { MjmlImage } from "@faire/mjml-react";
 import clsx from "clsx";
-import { registerStyles } from "../../styles/registerStyles.js";
-import { css } from "../../utils/css.js";
+import { MjmlImage } from "../../components/image/MjmlImage.js";
 import { usePixelImageBlockData } from "./usePixelImageBlockData.js";
 /**
  * Renders a pixel-image from the DAM as `MjmlImage`. Must be placed within an
@@ -15,10 +13,3 @@ export function MjmlPixelImageBlock({ data, width, largestPossibleRenderWidth, a
     }
     return (_jsx(MjmlImage, { src: imageData.imageUrl, width: imageData.defaultRenderWidth, height: imageData.desktopImageHeight, alt: imageData.alt, title: imageData.title, className: clsx("mjmlPixelImageBlock", className), ...imageProps }));
 }
-registerStyles((theme) => css `
-        ${theme.breakpoints.default.belowMediaQuery} {
-            .mjmlPixelImageBlock img {
-                height: auto !important;
-            }
-        }
-    `);

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/HtmlDivider.d.ts

@@ -0,0 +1,9 @@
+import type { ReactNode } from "react";
+import type { Theme } from "../../theme/themeTypes.js";
+import type { DividerProps } from "./dividerProps.js";
+export type HtmlDividerProps = DividerProps;
+/**
+ * Themed divider for use inside MJML ending tags or outside of the MJML context.
+ */
+export declare function HtmlDivider({ variant: variantProp, height: heightProp, backgroundColor: backgroundColorProp, backgroundImage: backgroundImageProp, className, style, }: HtmlDividerProps): ReactNode;
+export declare function generateHtmlDividerStyles(theme: Theme): string;

package/lib/components/divider/HtmlDivider.js

@@ -0,0 +1,43 @@
+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 { useOptionalTheme } from "../../theme/ThemeProvider.js";
+import { defaultDividerStyles } from "./defaultDividerStyles.js";
+import { generateResponsiveDividerCss } from "./generateResponsiveDividerCss.js";
+// U+200B keeps the cell from collapsing in clients that drop empty <td>s,
+// without contributing visible width.
+const zeroWidthSpace = String.fromCharCode(0x200b);
+/**
+ * Themed divider for use inside MJML ending tags or outside of the MJML context.
+ */
+export function HtmlDivider({ variant: variantProp, height: heightProp, backgroundColor: backgroundColorProp, backgroundImage: backgroundImageProp, className, style, }) {
+    const theme = useOptionalTheme();
+    if (theme === null && variantProp !== undefined) {
+        throw new Error("The `variant` prop requires being wrapped in a ThemeProvider or MjmlMailRoot.");
+    }
+    const themeDivider = theme?.divider ?? defaultDividerStyles;
+    const { defaultVariant, variants, ...baseStyles } = themeDivider;
+    const activeVariant = variantProp ?? defaultVariant;
+    const variantStyles = activeVariant ? variants?.[activeVariant] : undefined;
+    const mergedStyles = variantStyles ? { ...baseStyles, ...variantStyles } : baseStyles;
+    const height = heightProp ?? getDefaultOrUndefined(mergedStyles.height);
+    const backgroundColor = backgroundColorProp ?? getDefaultOrUndefined(mergedStyles.backgroundColor);
+    const backgroundImage = backgroundImageProp ?? getDefaultOrUndefined(mergedStyles.backgroundImage);
+    const dividerStyle = {
+        height,
+        lineHeight: height === undefined ? undefined : `${height}px`,
+        fontSize: 0,
+        backgroundColor,
+        backgroundImage,
+        ...{ msoLineHeightRule: "exactly" },
+        ...style,
+    };
+    return (_jsx("table", { role: "presentation", cellPadding: 0, cellSpacing: 0, border: 0, width: "100%", className: clsx("htmlDivider", activeVariant && `htmlDivider--${activeVariant}`, className), children: _jsx("tbody", { children: _jsx("tr", { children: _jsx("td", { bgcolor: backgroundColor, height: height, style: dividerStyle, children: zeroWidthSpace }) }) }) }));
+}
+export function generateHtmlDividerStyles(theme) {
+    return generateResponsiveDividerCss(theme, {
+        styleSelector: (variantName) => `.htmlDivider--${variantName} td`,
+    });
+}
+registerStyles(generateHtmlDividerStyles);

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

@@ -0,0 +1,7 @@
+import type { ReactNode } from "react";
+import type { DividerProps } from "./dividerProps.js";
+export type MjmlDividerProps = DividerProps;
+/**
+ * Themed divider for use inside an `MjmlColumn`.
+ */
+export declare function MjmlDivider({ variant, height, backgroundColor, backgroundImage, className, style }: MjmlDividerProps): ReactNode;

package/lib/components/divider/MjmlDivider.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { MjmlRaw } from "@faire/mjml-react";
+import clsx from "clsx";
+import { useOptionalTheme } from "../../theme/ThemeProvider.js";
+import { HtmlDivider } from "./HtmlDivider.js";
+/**
+ * Themed divider for use inside an `MjmlColumn`.
+ */
+export function MjmlDivider({ variant, height, backgroundColor, backgroundImage, className, style }) {
+    const theme = useOptionalTheme();
+    const activeVariant = variant ?? theme?.divider.defaultVariant;
+    return (_jsx(MjmlRaw, { children: _jsx(HtmlDivider, { variant: variant, height: height, backgroundColor: backgroundColor, backgroundImage: backgroundImage, className: clsx("mjmlDivider", activeVariant && `mjmlDivider--${activeVariant}`, className), style: style }) }));
+}

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

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

package/lib/components/divider/defaultDividerStyles.js

@@ -0,0 +1,4 @@
+export const defaultDividerStyles = {
+    height: 4,
+    backgroundColor: "#000000",
+};

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

@@ -0,0 +1,51 @@
+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. Requires a
+     * theme (`ThemeProvider` or `MjmlMailRoot`) when set.
+     *
+     * Custom variants should be defined in the theme through module augmentation:
+     *
+     * ```ts
+     * declare module "@comet/mail-react" {
+     *     interface DividerVariants { thin: true; thick: true }
+     * }
+     * ```
+     *
+     * ```ts
+     * const theme = createTheme({
+     *     divider: {
+     *         variants: {
+     *             thin: { height: 1 },
+     *             thick: { height: 8 },
+     *         },
+     *     },
+     * });
+     * ```
+     *
+     * @defaultValue The theme's `divider.defaultVariant`, when set
+     */
+    variant?: DividerVariantName;
+    /**
+     * 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"`).
+     *
+     * @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;
+    style?: CSSProperties;
+}

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

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

package/lib/components/divider/generateResponsiveDividerCss.js

@@ -0,0 +1,15 @@
+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) {
+    return generateResponsiveVariantCss({
+        breakpoints: theme.breakpoints,
+        variants: theme.divider.variants,
+        groups: [{ selector: options.styleSelector, properties: dividerProperties }],
+    });
+}

package/lib/components/image/HtmlImage.d.ts

@@ -0,0 +1,11 @@
+import type { ComponentProps, ReactNode } from "react";
+export type HtmlImageProps = ComponentProps<"img">;
+/**
+ * Renders an `<img>` tag that adapts to its container width below the default
+ * breakpoint.
+ *
+ * Use within raw HTML context — HTML-only emails or
+ * [MJML ending tags](https://documentation.mjml.io/#ending-tags) like `MjmlRaw`.
+ * For MJML context, use `MjmlImage`.
+ */
+export declare function HtmlImage({ className, ...restProps }: HtmlImageProps): ReactNode;

package/lib/components/image/HtmlImage.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import clsx from "clsx";
+import { registerStyles } from "../../styles/registerStyles.js";
+import { css } from "../../utils/css.js";
+/**
+ * Renders an `<img>` tag that adapts to its container width below the default
+ * breakpoint.
+ *
+ * Use within raw HTML context — HTML-only emails or
+ * [MJML ending tags](https://documentation.mjml.io/#ending-tags) like `MjmlRaw`.
+ * For MJML context, use `MjmlImage`.
+ */
+export function HtmlImage({ className, ...restProps }) {
+    return _jsx("img", { className: clsx("htmlImage", className), ...restProps });
+}
+registerStyles((theme) => css `
+        ${theme.breakpoints.default.belowMediaQuery} {
+            .htmlImage {
+                width: 100%;
+                height: auto;
+            }
+        }
+    `);