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

package/README.md

@@ -1,26 +1,53 @@
 # @comet/mail-react
 
-Utilities for building HTML emails with React and MJML.
+Single-package solution for building HTML emails with React and MJML. Consumers install only `@comet/mail-react` (plus `react`) — never `@faire/mjml-react` directly.
 
-## Spec-driven development with OpenSpec
+The package:
 
-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.
+- re-exports all `@faire/mjml-react` MJML components (with prop types renamed to drop the `I` prefix);
+- extends some of them with extra props and features;
+- adds new components and utilities — block factories (`BlocksBlock`, `ListBlock`, `OneOfBlock`, `OptionalBlock`) for rendering Comet CMS block data, and a `css()` tagged template literal for IDE syntax highlighting.
 
-## Getting started
+Some components also ship in an `Html` variant for use inside MJML ending tags. These variants are additive — separate components alongside the `Mjml` versions, with their own API.
 
-- 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
+## Internal development
 
-## Suggested development workflow
+We extend `@faire/mjml-react` rather than fork it. A few rules keep that working:
 
-- 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
+- **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.
 
-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).
+### Styling
 
-## Suggested review workflow
+- **Inline first.** Components must render correctly without any `<style>` block — clients like Outlook ignore them.
+- **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)`.
 
-- 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
+### 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.
+
+### 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
+
+A changeset describes what changes for the consumer. If the public API and end-user behavior are unchanged, no changeset is needed.
+
+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
+
+If a change reverses a decision or shifts a convention recorded here, update this README in the same PR.
+
+## Consumer-facing companions
+
+- 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)
+
+When a change here affects usage patterns, component APIs, or styling conventions, update these alongside the library change.

package/lib/__stories__/examples/CustomBackgroundForFooter.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 { MjmlWrapper } from "../../components/wrapper/MjmlWrapper.js";
+import { createTheme } from "../../theme/createTheme.js";
+const config = {
+    title: "Examples/CustomBackgroundForFooter",
+    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(MjmlWrapper, { backgroundColor: "#dddddd", 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__/layout-patterns/AsymmetricTwoColumnLayout.stories.d.ts

@@ -0,0 +1,6 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+declare const config: Meta;
+export default config;
+export declare const SmallColumnLeft: StoryObj;
+export declare const SmallColumnRight: StoryObj;
+export declare const ReversedMobileStackOrder: StoryObj;

package/lib/__stories__/layout-patterns/AsymmetricTwoColumnLayout.stories.js

@@ -0,0 +1,107 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { MjmlColumn, MjmlImage, MjmlSpacer, MjmlWrapper } from "@faire/mjml-react";
+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: "Layout Patterns/Asymmetric Two-Column Layout",
+};
+export default config;
+const theme = createTheme({
+    text: {
+        defaultVariant: "body",
+        variants: {
+            heading: { fontSize: "22px", lineHeight: "28px", fontWeight: "bold" },
+            body: { fontSize: "16px", lineHeight: "24px" },
+        },
+    },
+});
+const SMALL_COLUMN_WIDTH = 120;
+const COLUMN_GAP = 20;
+const sectionIndent = getDefaultFromResponsiveValue(theme.sizes.contentIndentation);
+const sectionInnerWidth = theme.sizes.bodyWidth - 2 * sectionIndent;
+const fluidColumnWidth = sectionInnerWidth - SMALL_COLUMN_WIDTH;
+registerStyles((theme) => css `
+        ${theme.breakpoints.default.belowMediaQuery} {
+            .asymmetricLayoutLeft__fluidColumn {
+                width: calc(100% - ${SMALL_COLUMN_WIDTH}px) !important;
+                max-width: calc(100% - ${SMALL_COLUMN_WIDTH}px) !important;
+            }
+        }
+
+        ${theme.breakpoints.mobile.belowMediaQuery} {
+            .asymmetricLayoutLeft__fluidColumn {
+                width: 100% !important;
+                max-width: 100% !important;
+            }
+
+            .asymmetricLayoutLeft__smallColumn {
+                margin-bottom: 10px;
+            }
+
+            .asymmetricLayoutLeft__fluidColumn > table > tbody > tr > td {
+                padding-left: 0 !important;
+            }
+        }
+    `);
+export const SmallColumnLeft = {
+    parameters: { theme },
+    render: () => (_jsxs(_Fragment, { children: [_jsx(MjmlSection, { indent: true, children: _jsxs(MjmlColumn, { children: [_jsx(MjmlSpacer, { height: 30 }), _jsx(MjmlText, { variant: "heading", bottomSpacing: true, children: "Small column on the left" }), _jsx(MjmlText, { children: "A fixed-width column on the left with a fluid column taking the remaining space. On mobile, columns stack vertically with the small column on top." }), _jsx(MjmlSpacer, { height: 30 })] }) }), _jsxs(MjmlSection, { indent: true, children: [_jsx(MjmlColumn, { className: "asymmetricLayoutLeft__smallColumn", width: `${SMALL_COLUMN_WIDTH}px`, verticalAlign: "middle", children: _jsx(MjmlImage, { src: `https://picsum.photos/seed/1/${SMALL_COLUMN_WIDTH}/150`, alt: "Placeholder", align: "center", width: SMALL_COLUMN_WIDTH }) }), _jsxs(MjmlColumn, { className: "asymmetricLayoutLeft__fluidColumn", width: `${fluidColumnWidth}px`, paddingLeft: `${COLUMN_GAP}px`, verticalAlign: "middle", children: [_jsx(MjmlText, { variant: "heading", bottomSpacing: true, children: "Fluid column" }), _jsx(MjmlText, { children: "This column takes the remaining width after the fixed-width column. The gap between columns is created via padding on the fluid column's inner edge." })] })] }), _jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsx(MjmlSpacer, { height: 30 }) }) })] })),
+};
+registerStyles((theme) => css `
+        ${theme.breakpoints.default.belowMediaQuery} {
+            .asymmetricLayoutRight__fluidColumn {
+                width: calc(100% - ${SMALL_COLUMN_WIDTH}px) !important;
+                max-width: calc(100% - ${SMALL_COLUMN_WIDTH}px) !important;
+            }
+        }
+
+        ${theme.breakpoints.mobile.belowMediaQuery} {
+            .asymmetricLayoutRight__fluidColumn {
+                width: 100% !important;
+                max-width: 100% !important;
+            }
+
+            .asymmetricLayoutRight__smallColumn {
+                margin-top: 10px;
+            }
+
+            .asymmetricLayoutRight__fluidColumn > table > tbody > tr > td {
+                padding-right: 0 !important;
+            }
+        }
+    `);
+export const SmallColumnRight = {
+    parameters: { theme },
+    render: () => (_jsxs(_Fragment, { children: [_jsx(MjmlSection, { indent: true, children: _jsxs(MjmlColumn, { children: [_jsx(MjmlSpacer, { height: 30 }), _jsx(MjmlText, { variant: "heading", bottomSpacing: true, children: "Small column on the right" }), _jsx(MjmlText, { children: "A fluid column on the left with a fixed-width column on the right. On mobile, columns stack vertically with the fluid column on top." }), _jsx(MjmlSpacer, { height: 30 })] }) }), _jsxs(MjmlSection, { indent: true, children: [_jsxs(MjmlColumn, { className: "asymmetricLayoutRight__fluidColumn", width: `${fluidColumnWidth}px`, paddingRight: `${COLUMN_GAP}px`, verticalAlign: "middle", children: [_jsx(MjmlText, { variant: "heading", bottomSpacing: true, children: "Fluid column" }), _jsx(MjmlText, { children: "This column takes the remaining width after the fixed-width column. The gap between columns is created via padding on the fluid column's inner edge." })] }), _jsx(MjmlColumn, { className: "asymmetricLayoutRight__smallColumn", width: `${SMALL_COLUMN_WIDTH}px`, verticalAlign: "middle", children: _jsx(MjmlImage, { src: `https://picsum.photos/seed/2/${SMALL_COLUMN_WIDTH}/150`, alt: "Placeholder", align: "center", width: SMALL_COLUMN_WIDTH }) })] }), _jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsx(MjmlSpacer, { height: 30 }) }) })] })),
+};
+registerStyles((theme) => css `
+        ${theme.breakpoints.default.belowMediaQuery} {
+            .asymmetricLayoutRtl__fluidColumn {
+                width: calc(100% - ${SMALL_COLUMN_WIDTH}px) !important;
+                max-width: calc(100% - ${SMALL_COLUMN_WIDTH}px) !important;
+            }
+        }
+
+        ${theme.breakpoints.mobile.belowMediaQuery} {
+            .asymmetricLayoutRtl__fluidColumn {
+                width: 100% !important;
+                max-width: 100% !important;
+            }
+
+            .asymmetricLayoutRtl__smallColumn {
+                margin-bottom: 10px;
+            }
+
+            .asymmetricLayoutRtl__fluidColumn > table > tbody > tr > td {
+                padding-right: 0 !important;
+            }
+        }
+    `);
+export const ReversedMobileStackOrder = {
+    parameters: { theme },
+    render: () => (_jsxs(_Fragment, { children: [_jsx(MjmlSection, { indent: true, children: _jsxs(MjmlColumn, { children: [_jsx(MjmlSpacer, { height: 30 }), _jsx(MjmlText, { variant: "heading", bottomSpacing: true, children: "Small column on the right, stacks on top on mobile" }), _jsxs(MjmlText, { children: ["Uses ", _jsx("code", { children: "direction=\"rtl\"" }), " on the section to visually place the small column on the right on desktop, while keeping it first in source order so it stacks on top on mobile. A wrapper handles the indentation separately to avoid a 1px line artifact in Outlook."] }), _jsx(MjmlSpacer, { height: 30 })] }) }), _jsx(MjmlWrapper, { padding: `0 ${sectionIndent}px`, backgroundColor: theme.colors.background.content, children: _jsxs(MjmlSection, { direction: "rtl", children: [_jsx(MjmlColumn, { className: "asymmetricLayoutRtl__smallColumn", width: `${SMALL_COLUMN_WIDTH}px`, verticalAlign: "middle", children: _jsx(MjmlImage, { src: `https://picsum.photos/seed/3/${SMALL_COLUMN_WIDTH}/150`, alt: "Placeholder", align: "center", width: SMALL_COLUMN_WIDTH }) }), _jsxs(MjmlColumn, { className: "asymmetricLayoutRtl__fluidColumn", width: `${fluidColumnWidth}px`, paddingRight: `${COLUMN_GAP}px`, verticalAlign: "middle", children: [_jsx(MjmlText, { variant: "heading", bottomSpacing: true, children: "Fluid column" }), _jsxs(MjmlText, { children: ["Source order: small column first, fluid column second. On desktop, ", _jsx("code", { children: "direction=\"rtl\"" }), " flips the visual order so the fluid column appears on the left."] })] })] }) }), _jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsx(MjmlSpacer, { height: 30 }) }) })] })),
+};

package/lib/__stories__/layout-patterns/SymmetricFourColumnLayout.stories.d.ts

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

package/lib/__stories__/layout-patterns/SymmetricFourColumnLayout.stories.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { MjmlColumn, MjmlSpacer } from "@faire/mjml-react";
+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: "Layout Patterns/Symmetric Four-Column Layout",
+};
+export default config;
+const theme = createTheme({
+    text: {
+        defaultVariant: "body",
+        variants: {
+            heading: { fontSize: "22px", lineHeight: "28px", fontWeight: "bold" },
+            subheading: { fontSize: "16px", lineHeight: "22px", fontWeight: "bold" },
+            body: { fontSize: "14px", lineHeight: "20px" },
+        },
+    },
+});
+registerStyles((theme) => css `
+        ${theme.breakpoints.default.belowMediaQuery} {
+            .symmetricFourColumnsSection > table > tbody > tr > td {
+                display: flex !important;
+                flex-direction: column !important;
+                gap: 20px !important;
+            }
+
+            .symmetricFourColumnsSection__column {
+                flex: none !important;
+                width: 100% !important;
+                max-width: 100% !important;
+                display: block !important;
+            }
+
+            .symmetricFourColumnsSection__column > table > tbody > tr > td {
+                padding-left: 0 !important;
+                padding-right: 0 !important;
+            }
+        }
+    `);
+export const Default = {
+    parameters: { theme },
+    render: () => {
+        const SymmetricFourColumnSection = () => {
+            const columnGap = 20;
+            const halfColumnGap = columnGap / 2;
+            const availableContentWidth = theme.sizes.bodyWidth - 2 * getDefaultFromResponsiveValue(theme.sizes.contentIndentation);
+            const contentWidthPerColumn = (availableContentWidth - 3 * columnGap) / 4;
+            const outerColumnWidth = `${((contentWidthPerColumn + halfColumnGap) / availableContentWidth) * 100}%`;
+            const innerColumnWidth = `${((contentWidthPerColumn + columnGap) / availableContentWidth) * 100}%`;
+            return (_jsxs(MjmlSection, { indent: true, className: "symmetricFourColumnsSection", children: [_jsxs(MjmlColumn, { width: outerColumnWidth, paddingRight: halfColumnGap, className: "symmetricFourColumnsSection__column", children: [_jsx(MjmlText, { variant: "subheading", bottomSpacing: true, children: "First" }), _jsx(MjmlText, { children: "Minima ea distinctio quisquam. Illo reiciendis non officiis consectetur." })] }), _jsxs(MjmlColumn, { width: innerColumnWidth, paddingLeft: halfColumnGap, paddingRight: halfColumnGap, className: "symmetricFourColumnsSection__column", children: [_jsx(MjmlText, { variant: "subheading", bottomSpacing: true, children: "Second" }), _jsx(MjmlText, { children: "Numquam aut voluptas numquam aspernatur. Consequatur quidem omnis dolorem natus." })] }), _jsxs(MjmlColumn, { width: innerColumnWidth, paddingLeft: halfColumnGap, paddingRight: halfColumnGap, className: "symmetricFourColumnsSection__column", children: [_jsx(MjmlText, { variant: "subheading", bottomSpacing: true, children: "Third" }), _jsx(MjmlText, { children: "Occaecati vel possimus similique reiciendis iure rerum sit architecto." })] }), _jsxs(MjmlColumn, { width: outerColumnWidth, paddingLeft: halfColumnGap, className: "symmetricFourColumnsSection__column", children: [_jsx(MjmlText, { variant: "subheading", bottomSpacing: true, children: "Fourth" }), _jsx(MjmlText, { children: "Voluptas laudantium cupiditate aut repudiandae iste fugiat nam quas debitis." })] })] }));
+        };
+        return (_jsxs(_Fragment, { children: [_jsx(MjmlSection, { indent: true, children: _jsxs(MjmlColumn, { children: [_jsx(MjmlSpacer, { height: 30 }), _jsx(MjmlText, { variant: "heading", bottomSpacing: true, children: "Four column layout" }), _jsx(MjmlText, { children: "Four columns follow the same compensation pattern as three columns. The two inner columns each get a wider width to absorb their double-sided padding. On mobile, a flex reset neutralizes the desktop widths so columns can stack equally." }), _jsx(MjmlSpacer, { height: 30 })] }) }), _jsx(SymmetricFourColumnSection, {}), _jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsx(MjmlSpacer, { height: 30 }) }) })] }));
+    },
+};

package/lib/__stories__/layout-patterns/SymmetricThreeColumnLayout.stories.d.ts

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

package/lib/__stories__/layout-patterns/SymmetricThreeColumnLayout.stories.js

@@ -0,0 +1,104 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { MjmlColumn, MjmlSpacer } from "@faire/mjml-react";
+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: "Layout Patterns/Symmetric Three-Column Layout",
+};
+export default config;
+const theme = createTheme({
+    text: {
+        defaultVariant: "body",
+        variants: {
+            heading: { fontSize: "22px", lineHeight: "28px", fontWeight: "bold" },
+            subheading: { fontSize: "16px", lineHeight: "22px", fontWeight: "bold" },
+            body: { fontSize: "14px", lineHeight: "20px" },
+        },
+    },
+});
+registerStyles((theme) => css `
+        ${theme.breakpoints.default.belowMediaQuery} {
+            .symmetricThreeColumnsSection > table > tbody > tr > td {
+                display: flex !important;
+                gap: 20px !important;
+            }
+
+            .symmetricThreeColumnsSection__column {
+                flex: 1 1 0% !important;
+                width: auto !important;
+                max-width: none !important;
+                display: block !important;
+            }
+
+            .symmetricThreeColumnsSection__column > table > tbody > tr > td {
+                padding-left: 0 !important;
+                padding-right: 0 !important;
+            }
+        }
+
+        ${theme.breakpoints.mobile.belowMediaQuery} {
+            .symmetricThreeColumnsSection > table > tbody > tr > td {
+                flex-direction: column !important;
+            }
+
+            .symmetricThreeColumnsSection__column {
+                flex: none !important;
+                width: 100% !important;
+                max-width: 100% !important;
+            }
+        }
+    `);
+export const Default = {
+    parameters: { theme },
+    render: () => {
+        const SymmetricThreeColumnSection = () => {
+            const columnGap = 20;
+            const halfColumnGap = columnGap / 2;
+            const availableContentWidth = theme.sizes.bodyWidth - 2 * getDefaultFromResponsiveValue(theme.sizes.contentIndentation);
+            const contentWidthPerColumn = (availableContentWidth - 2 * columnGap) / 3;
+            const outerColumnWidth = `${((contentWidthPerColumn + halfColumnGap) / availableContentWidth) * 100}%`;
+            const innerColumnWidth = `${((contentWidthPerColumn + columnGap) / availableContentWidth) * 100}%`;
+            return (_jsxs(MjmlSection, { indent: true, className: "symmetricThreeColumnsSection", children: [_jsxs(MjmlColumn, { width: outerColumnWidth, paddingRight: halfColumnGap, className: "symmetricThreeColumnsSection__column", children: [_jsx(MjmlText, { variant: "subheading", bottomSpacing: true, children: "First column" }), _jsx(MjmlText, { children: "Minima ea distinctio quisquam. Illo reiciendis non officiis consectetur. Ratione perferendis distinctio sapiente est." })] }), _jsxs(MjmlColumn, { width: innerColumnWidth, paddingLeft: halfColumnGap, paddingRight: halfColumnGap, className: "symmetricThreeColumnsSection__column", children: [_jsx(MjmlText, { variant: "subheading", bottomSpacing: true, children: "Second column" }), _jsx(MjmlText, { children: "Numquam aut voluptas numquam aspernatur. Consequatur quidem omnis dolorem natus quis soluta. Est recusandae delectus." })] }), _jsxs(MjmlColumn, { width: outerColumnWidth, paddingLeft: halfColumnGap, className: "symmetricThreeColumnsSection__column", children: [_jsx(MjmlText, { variant: "subheading", bottomSpacing: true, children: "Third column" }), _jsx(MjmlText, { children: "Occaecati vel possimus similique reiciendis iure rerum sit architecto. Voluptas laudantium cupiditate aut repudiandae iste." })] })] }));
+        };
+        return (_jsxs(_Fragment, { children: [_jsx(MjmlSection, { indent: true, children: _jsxs(MjmlColumn, { children: [_jsx(MjmlSpacer, { height: 30 }), _jsx(MjmlText, { variant: "heading", bottomSpacing: true, children: "Three column layout" }), _jsx(MjmlText, { children: "Three columns require explicit width compensation. Inner columns have padding on both sides while outer columns only have it on one side, so inner columns are given a wider width to keep all content areas equal. On mobile, a flex reset neutralizes the desktop widths so columns can size equally and then stack." }), _jsx(MjmlSpacer, { height: 30 })] }) }), _jsx(SymmetricThreeColumnSection, {}), _jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsx(MjmlSpacer, { height: 30 }) }) })] }));
+    },
+};
+registerStyles((theme) => css `
+        ${theme.breakpoints.default.belowMediaQuery} {
+            .neverStackingThreeColumnsSection > table > tbody > tr > td > div {
+                display: flex !important;
+                gap: 20px !important;
+            }
+
+            .neverStackingThreeColumnsSection__column {
+                flex: 1 1 0% !important;
+                width: auto !important;
+                max-width: none !important;
+                display: block !important;
+            }
+
+            .neverStackingThreeColumnsSection__column > table > tbody > tr > td {
+                padding-left: 0 !important;
+                padding-right: 0 !important;
+            }
+        }
+    `);
+export const NeverStacks = {
+    parameters: { theme },
+    render: () => {
+        const NeverStackingThreeColumnSection = () => {
+            const columnGap = 20;
+            const halfColumnGap = columnGap / 2;
+            const availableContentWidth = theme.sizes.bodyWidth - 2 * getDefaultFromResponsiveValue(theme.sizes.contentIndentation);
+            const contentWidthPerColumn = (availableContentWidth - 2 * columnGap) / 3;
+            const outerColumnWidth = `${((contentWidthPerColumn + halfColumnGap) / availableContentWidth) * 100}%`;
+            const innerColumnWidth = `${((contentWidthPerColumn + columnGap) / availableContentWidth) * 100}%`;
+            return (_jsxs(MjmlSection, { indent: true, disableResponsiveBehavior: true, className: "neverStackingThreeColumnsSection", children: [_jsxs(MjmlColumn, { width: outerColumnWidth, paddingRight: halfColumnGap, className: "neverStackingThreeColumnsSection__column", children: [_jsx(MjmlText, { variant: "subheading", bottomSpacing: true, children: "Foo" }), _jsx(MjmlText, { children: "Lorem" })] }), _jsxs(MjmlColumn, { width: innerColumnWidth, paddingLeft: halfColumnGap, paddingRight: halfColumnGap, className: "neverStackingThreeColumnsSection__column", children: [_jsx(MjmlText, { variant: "subheading", bottomSpacing: true, children: "Bar" }), _jsx(MjmlText, { children: "Ipsum" })] }), _jsxs(MjmlColumn, { width: outerColumnWidth, paddingLeft: halfColumnGap, className: "neverStackingThreeColumnsSection__column", children: [_jsx(MjmlText, { variant: "subheading", bottomSpacing: true, children: "Baz" }), _jsx(MjmlText, { children: "Dolor" })] })] }));
+        };
+        return (_jsxs(_Fragment, { children: [_jsx(MjmlSection, { indent: true, children: _jsxs(MjmlColumn, { children: [_jsx(MjmlSpacer, { height: 30 }), _jsx(MjmlText, { variant: "heading", bottomSpacing: true, children: "Three columns that never stack" }), _jsx(MjmlText, { bottomSpacing: true, children: "Same width compensation and flex-reset mechanic as the default three-column layout, without the mobile stacking override so columns stay side-by-side at every viewport." }), _jsxs(MjmlText, { bottomSpacing: true, children: [_jsx("code", { children: "disableResponsiveBehavior" }), " wraps the columns in an ", _jsx("code", { children: "MjmlGroup" }), " internally so MJML's own mobile auto-stack is suppressed even in clients that ignore the flex CSS. Because of that wrapper, the flex reset targets one level deeper (", _jsx("code", { children: "\u2026 > td > div" }), ") than in the default layout."] }), _jsx(MjmlText, { children: "Suitable for short, fixed-value rows \u2014 metrics, numeric summaries, icon strips \u2014 that remain readable even when narrow." }), _jsx(MjmlSpacer, { height: 30 })] }) }), _jsx(NeverStackingThreeColumnSection, {}), _jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsx(MjmlSpacer, { height: 30 }) }) })] }));
+    },
+};

package/lib/__stories__/layout-patterns/SymmetricTwoColumnLayout.stories.d.ts

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

package/lib/__stories__/layout-patterns/SymmetricTwoColumnLayout.stories.js

@@ -0,0 +1,47 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { MjmlColumn, MjmlSpacer } from "@faire/mjml-react";
+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 { css } from "../../utils/css.js";
+const config = {
+    title: "Layout Patterns/Symmetric Two-Column Layout",
+};
+export default config;
+const theme = createTheme({
+    text: {
+        defaultVariant: "body",
+        variants: {
+            heading: { fontSize: "22px", lineHeight: "28px", fontWeight: "bold" },
+            subheading: { fontSize: "16px", lineHeight: "22px", fontWeight: "bold" },
+            body: { fontSize: "14px", lineHeight: "20px" },
+        },
+    },
+});
+registerStyles((theme) => css `
+        ${theme.breakpoints.mobile.belowMediaQuery} {
+            .twoColumnsSection__leftColumn > table > tbody > tr > td {
+                padding-right: 0 !important;
+            }
+
+            .twoColumnsSection__rightColumn > table > tbody > tr > td {
+                padding-left: 0 !important;
+            }
+
+            .twoColumnsSection__leftColumn {
+                margin-bottom: 20px;
+            }
+        }
+    `);
+export const Default = {
+    parameters: { theme },
+    render: () => {
+        const TwoColumnsSection = () => {
+            const columnGap = 20;
+            const halfGap = columnGap / 2;
+            return (_jsxs(MjmlSection, { indent: true, className: "twoColumnsSection", children: [_jsxs(MjmlColumn, { className: "twoColumnsSection__leftColumn", paddingRight: halfGap, children: [_jsx(MjmlText, { variant: "subheading", bottomSpacing: true, children: "Left column" }), _jsx(MjmlText, { children: "Minima ea distinctio quisquam. Illo reiciendis non officiis consectetur. Ratione perferendis distinctio sapiente est. Dolor consequatur qui excepturi natus." })] }), _jsxs(MjmlColumn, { className: "twoColumnsSection__rightColumn", paddingLeft: halfGap, children: [_jsx(MjmlText, { variant: "subheading", bottomSpacing: true, children: "Right column" }), _jsx(MjmlText, { children: "Numquam aut voluptas numquam aspernatur. Consequatur quidem omnis dolorem natus quis soluta. Est recusandae delectus sed sed deserunt velit quia." })] })] }));
+        };
+        return (_jsxs(_Fragment, { children: [_jsx(MjmlSection, { indent: true, children: _jsxs(MjmlColumn, { children: [_jsx(MjmlSpacer, { height: 30 }), _jsx(MjmlText, { variant: "heading", bottomSpacing: true, children: "Two column layout" }), _jsx(MjmlText, { children: "Two columns with equal widths split evenly by MJML. Each column gets half-gap padding on its inner side to create the 20px gap. No explicit width calculation is needed." }), _jsx(MjmlSpacer, { height: 30 })] }) }), _jsx(TwoColumnsSection, {}), _jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsx(MjmlSpacer, { height: 30 }) }) })] }));
+    },
+};

package/lib/blocks/factories/BlocksBlock.d.ts

@@ -1,4 +1,4 @@
-import { type SupportedBlocks } from "./types.js";
+import type { SupportedBlocks } from "./types.js";
 interface Props {
     supportedBlocks: SupportedBlocks;
     data: {

package/lib/blocks/factories/OneOfBlock.d.ts

@@ -1,5 +1,5 @@
-import { type PropsWithChildren } from "react";
-import { type SupportedBlocks } from "./types.js";
+import type { PropsWithChildren } from "react";
+import type { SupportedBlocks } from "./types.js";
 interface Props extends PropsWithChildren {
     data: {
         block?: {

package/lib/blocks/factories/OptionalBlock.d.ts

@@ -1,4 +1,4 @@
-import { type PropsWithChildren, type ReactNode } from "react";
+import type { PropsWithChildren, ReactNode } from "react";
 interface Props extends PropsWithChildren {
     block: (props: any) => ReactNode;
     data: {

package/lib/blocks/factories/types.d.ts

@@ -1,4 +1,4 @@
-import { type ReactNode } from "react";
+import type { ReactNode } from "react";
 export interface SupportedBlocks {
     [key: string]: (props: any) => ReactNode | undefined;
 }

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

@@ -0,0 +1,11 @@
+import type { ComponentProps, ReactNode } from "react";
+import type { PixelImageBlockBaseProps } from "./common.js";
+export type HtmlPixelImageBlockProps = Omit<ComponentProps<"img">, "src" | "width" | "height"> & PixelImageBlockBaseProps;
+/**
+ * Renders a pixel-image from the DAM as a raw `<img>` tag.
+ *
+ * Use within raw HTML context — HTML-only emails or
+ * [MJML ending tags](https://documentation.mjml.io/#ending-tags) like `MjmlRaw`.
+ * For MJML context, use `MjmlPixelImageBlock`.
+ */
+export declare function HtmlPixelImageBlock({ data, width, largestPossibleRenderWidth, aspectRatio, className, ...imgProps }: HtmlPixelImageBlockProps): ReactNode;

package/lib/blocks/pixelImage/HtmlPixelImageBlock.js

@@ -0,0 +1,27 @@
+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 { usePixelImageBlockData } from "./usePixelImageBlockData.js";
+/**
+ * Renders a pixel-image from the DAM as a raw `<img>` tag.
+ *
+ * Use within raw HTML context — HTML-only emails or
+ * [MJML ending tags](https://documentation.mjml.io/#ending-tags) like `MjmlRaw`.
+ * For MJML context, use `MjmlPixelImageBlock`.
+ */
+export function HtmlPixelImageBlock({ data, width, largestPossibleRenderWidth, aspectRatio, className, ...imgProps }) {
+    const imageData = usePixelImageBlockData({ data, defaultRenderWidth: width, largestPossibleRenderWidth, aspectRatio });
+    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 }));
+}
+registerStyles((theme) => css `
+        ${theme.breakpoints.default.belowMediaQuery} {
+            .htmlPixelImageBlock {
+                width: 100%;
+                height: auto;
+            }
+        }
+    `);

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

@@ -0,0 +1,9 @@
+import { type IMjmlImageProps } from "@faire/mjml-react";
+import type { ReactNode } from "react";
+import type { PixelImageBlockBaseProps } from "./common.js";
+export type MjmlPixelImageBlockProps = Omit<IMjmlImageProps, "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`.
+ */
+export declare function MjmlPixelImageBlock({ data, width, largestPossibleRenderWidth, aspectRatio, className, ...imageProps }: MjmlPixelImageBlockProps): ReactNode;

package/lib/blocks/pixelImage/MjmlPixelImageBlock.js

@@ -0,0 +1,24 @@
+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 { usePixelImageBlockData } from "./usePixelImageBlockData.js";
+/**
+ * Renders a pixel-image from the DAM as `MjmlImage`. Must be placed within an
+ * `MjmlColumn`. For raw HTML context, use `HtmlPixelImageBlock`.
+ */
+export function MjmlPixelImageBlock({ data, width, largestPossibleRenderWidth, aspectRatio, className, ...imageProps }) {
+    const imageData = usePixelImageBlockData({ data, defaultRenderWidth: width, largestPossibleRenderWidth, aspectRatio });
+    if (!imageData) {
+        return null;
+    }
+    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/pixelImage/__stories__/HtmlPixelImageBlock.stories.d.ts

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