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

package/README.md

@@ -1,26 +1,105 @@
 # @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.
+- **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.
 
-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
+### 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.
+
+### 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.
+
+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.
+
+### 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.
+
+## 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.
+
+## Consumer-facing 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)
+
+When a change here affects usage patterns, component APIs, or styling conventions, update these alongside the library change.

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

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { MjmlColumn, MjmlImage, MjmlSpacer, MjmlWrapper } from "@faire/mjml-react";
+import { MjmlColumn, MjmlSpacer, MjmlWrapper } from "@faire/mjml-react";
+import { MjmlImage } from "../../components/image/MjmlImage.js";
 import { MjmlSection } from "../../components/section/MjmlSection.js";
 import { MjmlText } from "../../components/text/MjmlText.js";
 import { registerStyles } from "../../styles/registerStyles.js";

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,18 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import clsx from "clsx";
+import { HtmlImage } from "../../components/image/HtmlImage.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(HtmlImage, { src: imageData.imageUrl, width: imageData.defaultRenderWidth, height: imageData.desktopImageHeight, alt: imageData.alt, title: imageData.title, className: clsx("htmlPixelImageBlock", className), ...imgProps }));
+}

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

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

package/lib/blocks/pixelImage/MjmlPixelImageBlock.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import clsx from "clsx";
+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
+ * `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 }));
+}

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;

package/lib/blocks/pixelImage/__stories__/HtmlPixelImageBlock.stories.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MjmlColumn, MjmlRaw } from "@faire/mjml-react";
+import { MjmlMailRoot } from "../../../components/mailRoot/MjmlMailRoot.js";
+import { MjmlSection } from "../../../components/section/MjmlSection.js";
+import { HtmlPixelImageBlock } from "../HtmlPixelImageBlock.js";
+import { exampleBlockData } from "./exampleBlockData.js";
+const config = {
+    title: "Components/Blocks/HtmlPixelImageBlock",
+    component: HtmlPixelImageBlock,
+    tags: ["autodocs"],
+    parameters: {
+        mailRoot: false,
+        docs: {
+            description: {
+                component: "Renders a pixel-image from the DAM as a raw `<img>` tag, for use in HTML-only emails or inside MJML ending tags such as `MjmlRaw`.\n\n_Note: this story may fail to load the actual image when the API fixtures don't include the referenced DAM file._",
+            },
+        },
+    },
+    argTypes: {
+        data: { control: false },
+        aspectRatio: {
+            control: "select",
+            options: ["inherit", "16x9", "4x3", "3x2", "3x1", "2x1", "1x1", "1x2", "1x3", "2x3", "3x4", "9x16"],
+        },
+    },
+    args: {
+        data: exampleBlockData,
+        width: 600,
+    },
+};
+export default config;
+export const Default = {
+    render: (args) => (_jsx(MjmlMailRoot, { config: {
+            pixelImageBlock: {
+                validSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 2560, 3200, 3840],
+                baseUrl: "",
+            },
+        }, children: _jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsx(MjmlRaw, { children: _jsx(HtmlPixelImageBlock, { ...args }) }) }) }) })),
+};
+export const AspectRatioOverride = {
+    parameters: {
+        docs: {
+            description: {
+                story: "Renders the same DAM image at its native aspect ratio and overridden to `16x9`, demonstrating how the `aspectRatio` prop reframes the rendered image without changing the source DAM record.",
+            },
+        },
+    },
+    render: (args) => (_jsx(MjmlMailRoot, { config: {
+            pixelImageBlock: {
+                validSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 2560, 3200, 3840],
+                baseUrl: "",
+            },
+        }, children: _jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsxs(MjmlRaw, { children: [_jsx(HtmlPixelImageBlock, { ...args }), _jsx(HtmlPixelImageBlock, { ...args, aspectRatio: "16x9" })] }) }) }) })),
+};

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

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

package/lib/blocks/pixelImage/__stories__/MjmlPixelImageBlock.stories.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MjmlColumn } from "@faire/mjml-react";
+import { MjmlMailRoot } from "../../../components/mailRoot/MjmlMailRoot.js";
+import { MjmlSection } from "../../../components/section/MjmlSection.js";
+import { MjmlPixelImageBlock } from "../MjmlPixelImageBlock.js";
+import { exampleBlockData } from "./exampleBlockData.js";
+const config = {
+    title: "Components/Blocks/MjmlPixelImageBlock",
+    component: MjmlPixelImageBlock,
+    tags: ["autodocs"],
+    parameters: {
+        mailRoot: false,
+        docs: {
+            description: {
+                component: "Renders a pixel-image from the DAM as `MjmlImage`. Must be placed within an `MjmlColumn`.\n\n_Note: this story may fail to load the actual image when the API fixtures don't include the referenced DAM file._",
+            },
+        },
+    },
+    argTypes: {
+        data: { control: false },
+        aspectRatio: {
+            control: "select",
+            options: ["inherit", "16x9", "4x3", "3x2", "3x1", "2x1", "1x1", "1x2", "1x3", "2x3", "3x4", "9x16"],
+        },
+    },
+    args: {
+        data: exampleBlockData,
+        width: 600,
+    },
+};
+export default config;
+export const Default = {
+    render: (args) => (_jsx(MjmlMailRoot, { config: {
+            pixelImageBlock: {
+                validSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 2560, 3200, 3840],
+                baseUrl: "",
+            },
+        }, children: _jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsx(MjmlPixelImageBlock, { ...args }) }) }) })),
+};
+export const AspectRatioOverride = {
+    parameters: {
+        docs: {
+            description: {
+                story: "Renders the same DAM image at its native aspect ratio and overridden to `16x9`, demonstrating how the `aspectRatio` prop reframes the rendered image without changing the source DAM record.",
+            },
+        },
+    },
+    render: (args) => (_jsx(MjmlMailRoot, { config: {
+            pixelImageBlock: {
+                validSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 2560, 3200, 3840],
+                baseUrl: "",
+            },
+        }, children: _jsx(MjmlSection, { indent: true, children: _jsxs(MjmlColumn, { children: [_jsx(MjmlPixelImageBlock, { ...args }), _jsx(MjmlPixelImageBlock, { ...args, aspectRatio: "16x9" })] }) }) })),
+};

package/lib/blocks/pixelImage/__stories__/exampleBlockData.d.ts

@@ -0,0 +1,2 @@
+import type { PixelImageBlockData } from "../../../blocks.generated.js";
+export declare const exampleBlockData: PixelImageBlockData;

package/lib/blocks/pixelImage/__stories__/exampleBlockData.js

@@ -0,0 +1,19 @@
+export const exampleBlockData = {
+    damFile: {
+        id: "example-image",
+        name: "example-image.jpg",
+        size: 1000000,
+        mimetype: "image/jpeg",
+        contentHash: "example-hash",
+        archived: false,
+        scope: { domain: "at" },
+        fileUrl: "https://picsum.photos/seed/comet-pixel-image/1000/1000",
+        image: {
+            width: 1000,
+            height: 1000,
+            cropArea: { focalPoint: "SMART" },
+            dominantColor: "#000000",
+        },
+    },
+    urlTemplate: "https://picsum.photos/seed/comet-pixel-image/$resizeWidth/$resizeHeight",
+};

package/lib/blocks/pixelImage/__tests__/usePixelImageBlockConfig.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/blocks/pixelImage/__tests__/usePixelImageBlockConfig.test.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { ConfigProvider } from "../../../config/ConfigProvider.js";
+import { usePixelImageBlockConfig } from "../usePixelImageBlockConfig.js";
+function ConfigProbe() {
+    usePixelImageBlockConfig();
+    return null;
+}
+describe("usePixelImageBlockConfig", () => {
+    it("throws when config.pixelImageBlock is unset", () => {
+        expect(() => renderToStaticMarkup(_jsx(ConfigProbe, {}))).toThrowError(/`pixelImageBlock` must be set/);
+    });
+    it("error message points at MjmlMailRoot and ConfigProvider", () => {
+        expect(() => renderToStaticMarkup(_jsx(ConfigProbe, {}))).toThrowError(/MjmlMailRoot/);
+        expect(() => renderToStaticMarkup(_jsx(ConfigProbe, {}))).toThrowError(/ConfigProvider/);
+    });
+    it("does not throw when config.pixelImageBlock is provided", () => {
+        expect(() => renderToStaticMarkup(_jsx(ConfigProvider, { config: { pixelImageBlock: { validSizes: [640, 1280], baseUrl: "http://localhost:3000" } }, children: _jsx(ConfigProbe, {}) }))).not.toThrow();
+    });
+});

package/lib/blocks/pixelImage/__tests__/usePixelImageBlockData.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/blocks/pixelImage/__tests__/usePixelImageBlockData.test.js

@@ -0,0 +1,205 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { ConfigProvider } from "../../../config/ConfigProvider.js";
+import { createTheme } from "../../../theme/createTheme.js";
+import { ThemeProvider } from "../../../theme/ThemeProvider.js";
+import { usePixelImageBlockData } from "../usePixelImageBlockData.js";
+function captureUsePixelImageData({ data, defaultRenderWidth, largestPossibleRenderWidth, aspectRatio, config }) {
+    const captured = { value: undefined };
+    function Probe() {
+        captured.value = usePixelImageBlockData({ data, defaultRenderWidth, largestPossibleRenderWidth, aspectRatio });
+        return null;
+    }
+    renderToStaticMarkup(_jsx(ThemeProvider, { theme: createTheme(), children: _jsx(ConfigProvider, { config: config, children: _jsx(Probe, {}) }) }));
+    if (captured.value === undefined) {
+        throw new Error("Probe did not run");
+    }
+    return captured.value;
+}
+function expectNonNull(value) {
+    if (value === null) {
+        throw new Error("Expected non-null result from usePixelImageBlockData");
+    }
+    return value;
+}
+const validSizes = [320, 640, 1280, 2048];
+const baseUrl = "http://localhost:3000";
+const config = { pixelImageBlock: { validSizes, baseUrl } };
+const smartUrlTemplate = "/dam/images/abc/resize:$resizeWidth:$resizeHeight/photo.jpg";
+const smartImageData = {
+    damFile: {
+        id: "id-1",
+        name: "photo.jpg",
+        size: 1000,
+        mimetype: "image/jpeg",
+        contentHash: "hash",
+        archived: false,
+        fileUrl: "/dam/files/id-1.jpg",
+        image: {
+            width: 4000,
+            height: 2000,
+            cropArea: { focalPoint: "SMART" },
+        },
+    },
+    urlTemplate: smartUrlTemplate,
+};
+describe("usePixelImageBlockData — width selection", () => {
+    it("picks the smallest validSizes entry >= defaultRenderWidth × 2", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 200, config }));
+        expect(result.imageUrl).toContain(":640:");
+    });
+    it("picks an exact validSizes match when present", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 320, config }));
+        expect(result.imageUrl).toContain(":640:");
+    });
+    it("falls back to the largest validSizes entry when none qualifies", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 2000, config }));
+        expect(result.imageUrl).toContain(":2048:");
+    });
+    it("uses largestPossibleRenderWidth × 2 when defaultRenderWidth equals largestPossibleRenderWidth", () => {
+        const result = expectNonNull(captureUsePixelImageData({
+            data: smartImageData,
+            defaultRenderWidth: 600,
+            largestPossibleRenderWidth: 600,
+            config,
+        }));
+        expect(result.imageUrl).toContain(":1200:");
+    });
+    it("defaults largestPossibleRenderWidth to theme.sizes.bodyWidth (600) and triggers DPR-2 fixed path at width 600", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 600, config }));
+        expect(result.imageUrl).toContain(":1200:");
+    });
+});
+describe("usePixelImageBlockData — URL prefixing", () => {
+    it("prefixes a relative URL with config.pixelImageBlock.baseUrl", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 200, config }));
+        expect(result.imageUrl.startsWith(`${baseUrl}/dam/images/abc/`)).toBe(true);
+    });
+    it("does not prefix an absolute URL", () => {
+        const absoluteData = {
+            ...smartImageData,
+            urlTemplate: "https://cdn.example.com/$resizeWidth/$resizeHeight/photo.jpg",
+        };
+        const result = expectNonNull(captureUsePixelImageData({ data: absoluteData, defaultRenderWidth: 200, config }));
+        expect(result.imageUrl.startsWith("https://cdn.example.com/")).toBe(true);
+        expect(result.imageUrl.includes(baseUrl)).toBe(false);
+    });
+});
+describe("usePixelImageBlockData — aspect ratio", () => {
+    it("uses the natural image aspect ratio for SMART crop areas", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 200, config }));
+        expect(result.desktopImageHeight).toBe(100);
+        expect(result.imageUrl).toContain(":640:320/");
+    });
+    it("derives aspect ratio from crop dimensions for non-SMART crop areas", () => {
+        const nonSmartData = {
+            damFile: {
+                id: "id-2",
+                name: "photo2.jpg",
+                size: 1000,
+                mimetype: "image/jpeg",
+                contentHash: "hash",
+                archived: false,
+                fileUrl: "/dam/files/id-2.jpg",
+                image: {
+                    width: 4000,
+                    height: 2000,
+                    cropArea: { focalPoint: "CENTER", width: 50, height: 100, x: 25, y: 0 },
+                },
+            },
+            urlTemplate: smartUrlTemplate,
+        };
+        const result = expectNonNull(captureUsePixelImageData({ data: nonSmartData, defaultRenderWidth: 200, config }));
+        expect(result.desktopImageHeight).toBe(200);
+        expect(result.imageUrl).toContain(":640:640/");
+    });
+    it("throws when crop dimensions are missing on a non-SMART crop area", () => {
+        const malformedData = {
+            damFile: {
+                id: "id-3",
+                name: "photo3.jpg",
+                size: 1000,
+                mimetype: "image/jpeg",
+                contentHash: "hash",
+                archived: false,
+                fileUrl: "/dam/files/id-3.jpg",
+                image: {
+                    width: 4000,
+                    height: 2000,
+                    cropArea: { focalPoint: "CENTER" },
+                },
+            },
+            urlTemplate: smartUrlTemplate,
+        };
+        expect(() => captureUsePixelImageData({ data: malformedData, defaultRenderWidth: 200, config })).toThrow(/Missing crop dimensions/);
+    });
+});
+describe("usePixelImageBlockData — aspectRatio override", () => {
+    it("uses a numeric aspectRatio in place of the cropArea-derived ratio", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 200, aspectRatio: 16 / 9, config }));
+        expect(result.imageUrl).toContain(":640:360/");
+        expect(result.desktopImageHeight).toBe(113);
+    });
+    it.each([
+        ["WxH", "16x9"],
+        ["W:H", "16:9"],
+        ["W/H", "16/9"],
+    ])("parses string aspectRatio in %s form", (_label, value) => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 200, aspectRatio: value, config }));
+        expect(result.imageUrl).toContain(":640:360/");
+        expect(result.desktopImageHeight).toBe(113);
+    });
+    it("treats a single-token string as `width / 1`", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 200, aspectRatio: "2", config }));
+        expect(result.imageUrl).toContain(":640:320/");
+        expect(result.desktopImageHeight).toBe(100);
+    });
+    it("overrides a non-SMART cropArea ratio", () => {
+        const nonSmartData = {
+            damFile: {
+                id: "id-override",
+                name: "photo.jpg",
+                size: 1000,
+                mimetype: "image/jpeg",
+                contentHash: "hash",
+                archived: false,
+                fileUrl: "/dam/files/id-override.jpg",
+                image: {
+                    width: 4000,
+                    height: 2000,
+                    cropArea: { focalPoint: "CENTER", width: 50, height: 100, x: 25, y: 0 },
+                },
+            },
+            urlTemplate: smartUrlTemplate,
+        };
+        const result = expectNonNull(captureUsePixelImageData({ data: nonSmartData, defaultRenderWidth: 200, aspectRatio: "16x9", config }));
+        expect(result.imageUrl).toContain(":640:360/");
+        expect(result.desktopImageHeight).toBe(113);
+    });
+    it("throws when the aspectRatio string is malformed", () => {
+        expect(() => captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 200, aspectRatio: "not-a-ratio", config })).toThrow(/An error occurred while parsing the aspect ratio: not-a-ratio/);
+    });
+});
+describe("usePixelImageBlockData — incomplete data", () => {
+    it("returns null when damFile is absent", () => {
+        const result = captureUsePixelImageData({ data: { urlTemplate: smartUrlTemplate }, defaultRenderWidth: 200, config });
+        expect(result).toBeNull();
+    });
+    it("returns null when damFile.image is absent", () => {
+        const noImageData = {
+            damFile: {
+                id: "id-4",
+                name: "no-image.jpg",
+                size: 0,
+                mimetype: "image/jpeg",
+                contentHash: "hash",
+                archived: false,
+                fileUrl: "/dam/files/id-4.jpg",
+            },
+            urlTemplate: smartUrlTemplate,
+        };
+        const result = captureUsePixelImageData({ data: noImageData, defaultRenderWidth: 200, config });
+        expect(result).toBeNull();
+    });
+});

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

@@ -0,0 +1,18 @@
+import type { PixelImageBlockData } from "../../blocks.generated.js";
+export type PixelImageBlockBaseProps = {
+    /** The block data to render. */
+    data: PixelImageBlockData;
+    /** Width at which the image is rendered, in the default/desktop breakpoint. */
+    width: number;
+    /**
+     * Largest possible width the image can be rendered at across breakpoints.
+     * Defaults to `theme.sizes.bodyWidth`. Use this when the image can stretch
+     * wider on a narrower breakpoint than its desktop render width.
+     */
+    largestPossibleRenderWidth?: number;
+    /**
+     * Aspect ratio for the rendered image.
+     * @example "16x9"
+     */
+    aspectRatio?: number | string;
+};

package/lib/blocks/pixelImage/common.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,5 @@
+import { type PixelImageBlockConfig } from "../../config/ConfigProvider.js";
+/**
+ * Reads `config.pixelImageBlock` from the configuration context and returns it narrowed to non-null.
+ */
+export declare function usePixelImageBlockConfig(): PixelImageBlockConfig;

package/lib/blocks/pixelImage/usePixelImageBlockConfig.js

@@ -0,0 +1,11 @@
+import { useConfig } from "../../config/ConfigProvider.js";
+/**
+ * Reads `config.pixelImageBlock` from the configuration context and returns it narrowed to non-null.
+ */
+export function usePixelImageBlockConfig() {
+    const { pixelImageBlock } = useConfig();
+    if (!pixelImageBlock) {
+        throw new Error("`pixelImageBlock` must be set in `config` on `MjmlMailRoot` or `ConfigProvider` to use the pixel-image configuration.");
+    }
+    return pixelImageBlock;
+}

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

@@ -0,0 +1,16 @@
+import type { PixelImageBlockData as PixelImageBlockSourceData } from "../../blocks.generated.js";
+interface UsePixelImageBlockDataProps {
+    data: PixelImageBlockSourceData;
+    defaultRenderWidth: number;
+    largestPossibleRenderWidth?: number;
+    aspectRatio?: number | string;
+}
+interface PixelImageBlockData {
+    imageUrl: string;
+    defaultRenderWidth: number;
+    desktopImageHeight: number;
+    alt: string | undefined;
+    title: string | undefined;
+}
+export declare function usePixelImageBlockData({ data: { damFile, cropArea, urlTemplate }, defaultRenderWidth, largestPossibleRenderWidth: passedLargestPossibleRenderWidth, aspectRatio: passedAspectRatio, }: UsePixelImageBlockDataProps): PixelImageBlockData | null;
+export {};