@dextinity/mail-react 2.0.0-canary-20260729062014

package/lib/styles/registerStyles.d.ts

@@ -0,0 +1,19 @@
+import type { IMjmlStyleProps } from "@faire/mjml-react";
+import type { Theme } from "../theme/themeTypes.js";
+import type { css } from "../utils/css.js";
+type StylesPayload = ReturnType<typeof css> | ((theme: Theme) => ReturnType<typeof css>);
+type MjmlStyleOptions = Partial<Omit<IMjmlStyleProps, "children">>;
+interface StyleRegistryEntry {
+    styles: StylesPayload;
+    mjmlStyleProps?: MjmlStyleOptions;
+}
+/**
+ * Registers CSS styles that will be rendered in the email head as `<mj-style>` elements.
+ *
+ * Styles can be static CSS strings (via the `css` tagged template) or functions that
+ * receive the theme and return a CSS string.
+ */
+export declare function registerStyles(styles: StylesPayload, mjmlStyleProps?: MjmlStyleOptions): void;
+/** Returns all registered style entries. */
+export declare function getRegisteredStyles(): ReadonlyMap<StylesPayload, StyleRegistryEntry>;
+export {};

package/lib/styles/registerStyles.js

@@ -0,0 +1,14 @@
+const registry = new Map();
+/**
+ * Registers CSS styles that will be rendered in the email head as `<mj-style>` elements.
+ *
+ * Styles can be static CSS strings (via the `css` tagged template) or functions that
+ * receive the theme and return a CSS string.
+ */
+export function registerStyles(styles, mjmlStyleProps) {
+    registry.set(styles, { styles, mjmlStyleProps });
+}
+/** Returns all registered style entries. */
+export function getRegisteredStyles() {
+    return registry;
+}

package/lib/theme/ThemeProvider.d.ts

@@ -0,0 +1,8 @@
+import { type PropsWithChildren, type ReactNode } from "react";
+import type { Theme } from "./themeTypes.js";
+export declare function ThemeProvider({ theme, children }: PropsWithChildren<{
+    theme: Theme;
+}>): ReactNode;
+export declare function useTheme(): Theme;
+/** Returns the current theme or `null` if no `ThemeProvider` is present. Internal use only. */
+export declare function useOptionalTheme(): Theme | null;

package/lib/theme/ThemeProvider.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const ThemeContext = createContext(null);
+export function ThemeProvider({ theme, children }) {
+    return _jsx(ThemeContext.Provider, { value: theme, children: children });
+}
+export function useTheme() {
+    const theme = useContext(ThemeContext);
+    if (theme === null) {
+        throw new Error("useTheme must be used within a ThemeProvider (or MjmlMailRoot).");
+    }
+    return theme;
+}
+/** Returns the current theme or `null` if no `ThemeProvider` is present. Internal use only. */
+export function useOptionalTheme() {
+    return useContext(ThemeContext);
+}

package/lib/theme/createBreakpoint.d.ts

@@ -0,0 +1,7 @@
+import type { ThemeBreakpoint } from "./themeTypes.js";
+/**
+ * Constructs a `ThemeBreakpoint` for use in `createTheme` overrides or
+ * `ThemeBreakpoints` module augmentation. Guarantees the `belowMediaQuery`
+ * string is always formatted correctly.
+ */
+export declare function createBreakpoint(value: number): ThemeBreakpoint;

package/lib/theme/createBreakpoint.js

@@ -0,0 +1,11 @@
+/**
+ * Constructs a `ThemeBreakpoint` for use in `createTheme` overrides or
+ * `ThemeBreakpoints` module augmentation. Guarantees the `belowMediaQuery`
+ * string is always formatted correctly.
+ */
+export function createBreakpoint(value) {
+    return {
+        value,
+        belowMediaQuery: `@media (max-width: ${value - 1}px)`,
+    };
+}

package/lib/theme/createTheme.d.ts

@@ -0,0 +1,24 @@
+import type { Theme, ThemeBackgroundColors, ThemeBreakpoints, ThemeButton, ThemeColors, ThemeDivider, ThemeSizes, ThemeText } from "./themeTypes.js";
+type CreateThemeOverrides = {
+    sizes?: Partial<ThemeSizes>;
+    breakpoints?: Partial<ThemeBreakpoints>;
+    text?: Partial<ThemeText>;
+    divider?: Partial<ThemeDivider>;
+    button?: Partial<ThemeButton>;
+    colors?: {
+        background?: Partial<ThemeBackgroundColors>;
+    } & Partial<Omit<ThemeColors, "background">>;
+};
+/**
+ * Creates a complete theme by merging optional overrides onto the default
+ * theme values.
+ *
+ * Breakpoint overrides must be `ThemeBreakpoint` objects constructed via
+ * `createBreakpoint`. Arbitrary breakpoint keys from `ThemeBreakpoints`
+ * module augmentation are supported and flow through to the result.
+ *
+ * `breakpoints.default` is always auto-derived from `sizes.bodyWidth` unless
+ * explicitly overridden.
+ */
+export declare function createTheme(overrides?: CreateThemeOverrides): Theme;
+export {};

package/lib/theme/createTheme.js

@@ -0,0 +1,32 @@
+import { createBreakpoint } from "./createBreakpoint.js";
+import { defaultTheme } from "./defaultTheme.js";
+/**
+ * Creates a complete theme by merging optional overrides onto the default
+ * theme values.
+ *
+ * Breakpoint overrides must be `ThemeBreakpoint` objects constructed via
+ * `createBreakpoint`. Arbitrary breakpoint keys from `ThemeBreakpoints`
+ * module augmentation are supported and flow through to the result.
+ *
+ * `breakpoints.default` is always auto-derived from `sizes.bodyWidth` unless
+ * explicitly overridden.
+ */
+export function createTheme(overrides) {
+    const resolvedSizes = { ...defaultTheme.sizes, ...overrides?.sizes };
+    return {
+        sizes: resolvedSizes,
+        breakpoints: {
+            ...defaultTheme.breakpoints,
+            default: createBreakpoint(resolvedSizes.bodyWidth),
+            ...overrides?.breakpoints,
+        },
+        text: { ...defaultTheme.text, ...overrides?.text },
+        divider: { ...defaultTheme.divider, ...overrides?.divider },
+        button: { ...defaultTheme.button, ...overrides?.button },
+        colors: {
+            ...defaultTheme.colors,
+            ...overrides?.colors,
+            background: { ...defaultTheme.colors.background, ...overrides?.colors?.background },
+        },
+    };
+}

package/lib/theme/defaultTheme.d.ts

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

package/lib/theme/defaultTheme.js

@@ -0,0 +1,27 @@
+import { defaultButtonStyles } from "../components/button/defaultButtonStyles.js";
+import { defaultDividerStyles } from "../components/divider/defaultDividerStyles.js";
+import { createBreakpoint } from "./createBreakpoint.js";
+export const defaultTheme = {
+    sizes: {
+        bodyWidth: 600,
+        contentIndentation: { default: 32, mobile: 16 },
+    },
+    breakpoints: {
+        default: createBreakpoint(600),
+        mobile: createBreakpoint(420),
+    },
+    text: {
+        fontFamily: "Arial, sans-serif",
+        fontSize: "16px",
+        lineHeight: "20px",
+        bottomSpacing: "16px",
+    },
+    divider: defaultDividerStyles,
+    button: defaultButtonStyles,
+    colors: {
+        background: {
+            body: "#F2F2F2",
+            content: "#FFFFFF",
+        },
+    },
+};

package/lib/theme/responsiveValue.d.ts

@@ -0,0 +1,31 @@
+import type { ThemeBreakpoints } from "./themeTypes.js";
+/**
+ * A value that can vary per breakpoint. A plain `T` is shorthand for
+ * `{ default: T }` (inline only, no responsive overrides).
+ *
+ * The object form requires a `default` key and optional keys matching
+ * `ThemeBreakpoints` (including keys added via module augmentation).
+ */
+export type ResponsiveValue<T = number> = T | (Partial<Record<keyof ThemeBreakpoints, T>> & {
+    default: T;
+});
+/**
+ * Returns the default (inline) value from a `ResponsiveValue`.
+ * For a plain value, returns it directly. For an object, returns the `default` property.
+ */
+export declare function getDefaultFromResponsiveValue<T = number>(value: ResponsiveValue<T>): T;
+/**
+ * Returns the default value from a `ResponsiveValue`, or `undefined` if the
+ * input is `undefined`. Useful for extracting inline prop values from optional
+ * theme properties.
+ */
+export declare function getDefaultOrUndefined<T>(value: ResponsiveValue<T> | undefined): T | undefined;
+/**
+ * Returns the non-default breakpoint overrides from a `ResponsiveValue`.
+ * For a plain value, returns an empty array. For an object, returns one
+ * entry per breakpoint key (excluding `default`).
+ */
+export declare function getResponsiveOverrides<T = number>(value: ResponsiveValue<T>): Array<{
+    breakpointKey: keyof ThemeBreakpoints;
+    value: T;
+}>;

package/lib/theme/responsiveValue.js

@@ -0,0 +1,34 @@
+function isResponsiveObject(value) {
+    return typeof value === "object" && value !== null && "default" in value;
+}
+/**
+ * Returns the default (inline) value from a `ResponsiveValue`.
+ * For a plain value, returns it directly. For an object, returns the `default` property.
+ */
+export function getDefaultFromResponsiveValue(value) {
+    return isResponsiveObject(value) ? value.default : value;
+}
+/**
+ * Returns the default value from a `ResponsiveValue`, or `undefined` if the
+ * input is `undefined`. Useful for extracting inline prop values from optional
+ * theme properties.
+ */
+export function getDefaultOrUndefined(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return getDefaultFromResponsiveValue(value);
+}
+/**
+ * Returns the non-default breakpoint overrides from a `ResponsiveValue`.
+ * For a plain value, returns an empty array. For an object, returns one
+ * entry per breakpoint key (excluding `default`).
+ */
+export function getResponsiveOverrides(value) {
+    if (!isResponsiveObject(value)) {
+        return [];
+    }
+    return Object.entries(value)
+        .filter(([key]) => key !== "default")
+        .map(([key, val]) => ({ breakpointKey: key, value: val }));
+}

package/lib/theme/themeTypes.d.ts

@@ -0,0 +1,204 @@
+import type { ResponsiveValue } from "./responsiveValue.js";
+/**
+ * Single source of truth for text style property names and their value types.
+ * Both `TextStyles` and `TextVariantStyles` are derived from this interface.
+ */
+interface TextStyleMap {
+    fontFamily: string;
+    fontSize: string;
+    fontWeight: string | number;
+    fontStyle: string;
+    lineHeight: string | number;
+    letterSpacing: string;
+    textDecoration: string;
+    textTransform: string;
+    color: string;
+    bottomSpacing: string;
+}
+/** Base text styles where each property holds a plain value. */
+export type TextStyles = {
+    [K in keyof TextStyleMap]?: TextStyleMap[K];
+};
+/** Variant text styles where each property supports responsive values. */
+export type TextVariantStyles = {
+    [K in keyof TextStyleMap]?: ResponsiveValue<TextStyleMap[K]>;
+};
+/**
+ * Defines the variants available on the `MjmlText` component.
+ *
+ * ```ts
+ * declare module "@dextinity/mail-react" {
+ *     interface TextVariants {
+ *         heading: true;
+ *         body: true;
+ *     }
+ * }
+ * ```
+ */
+export interface TextVariants {
+}
+type VariantsRecord = keyof TextVariants extends never ? Record<string, TextVariantStyles> : {
+    [K in keyof TextVariants]?: TextVariantStyles;
+};
+export type VariantName = keyof TextVariants extends never ? string : keyof TextVariants;
+/** Theme configuration for text styles, variants, and default variant. */
+export interface ThemeText extends TextStyles {
+    defaultVariant?: VariantName;
+    variants?: VariantsRecord;
+}
+/**
+ * Single source of truth for divider style property names and their value types.
+ * Both `DividerStyles` and `DividerVariantStyles` are derived from this interface.
+ */
+interface DividerStyleMap {
+    height: number;
+    backgroundColor: string;
+    backgroundImage: string;
+}
+/** Base divider styles where each property holds a plain value. */
+export type DividerStyles = {
+    [K in keyof DividerStyleMap]?: DividerStyleMap[K];
+};
+/** Variant divider styles where each property supports responsive values. */
+export type DividerVariantStyles = {
+    [K in keyof DividerStyleMap]?: ResponsiveValue<DividerStyleMap[K]>;
+};
+/**
+ * Defines the variants available on the `MjmlDivider` and `HtmlDivider` components.
+ *
+ * ```ts
+ * declare module "@dextinity/mail-react" {
+ *     interface DividerVariants {
+ *         thin: true;
+ *         thick: true;
+ *     }
+ * }
+ * ```
+ */
+export interface DividerVariants {
+}
+type DividerVariantsRecord = keyof DividerVariants extends never ? Record<string, DividerVariantStyles> : {
+    [K in keyof DividerVariants]?: DividerVariantStyles;
+};
+export type DividerVariantName = keyof DividerVariants extends never ? string : keyof DividerVariants;
+/** Theme configuration for divider styles, variants, and default variant. */
+export interface ThemeDivider extends DividerStyles {
+    defaultVariant?: DividerVariantName;
+    variants?: DividerVariantsRecord;
+}
+/**
+ * Single source of truth for button style property names and their value types.
+ * Both `ButtonStyles` and `ButtonVariantStyles` are derived from this interface.
+ *
+ * `padding` is the button's inner padding (the space around the label). It is
+ * deliberately distinct from `MjmlButton`'s `padding` prop, which is the outer
+ * spacing around the button.
+ */
+interface ButtonStyleMap {
+    color: string;
+    backgroundColor: string;
+    /**
+     * A background image — typically a gradient. Rendered as progressive
+     * enhancement on top of `backgroundColor`; clients that don't render it
+     * (notably Outlook) fall back to the solid color.
+     */
+    backgroundImage: string;
+    border: string;
+    borderRadius: string;
+    fontFamily: string;
+    fontSize: string;
+    fontWeight: string | number;
+    lineHeight: string | number;
+    padding: string;
+}
+/** Base button styles where each property holds a plain value. */
+export type ButtonStyles = {
+    [K in keyof ButtonStyleMap]?: ButtonStyleMap[K];
+};
+/** Variant button styles where each property supports responsive values. */
+export type ButtonVariantStyles = {
+    [K in keyof ButtonStyleMap]?: ResponsiveValue<ButtonStyleMap[K]>;
+};
+/**
+ * Defines the variants available on the `MjmlButton` and `HtmlButton` components.
+ *
+ * ```ts
+ * declare module "@dextinity/mail-react" {
+ *     interface ButtonVariants {
+ *         primary: true;
+ *         secondary: true;
+ *     }
+ * }
+ * ```
+ */
+export interface ButtonVariants {
+}
+type ButtonVariantsRecord = keyof ButtonVariants extends never ? Record<string, ButtonVariantStyles> : {
+    [K in keyof ButtonVariants]?: ButtonVariantStyles;
+};
+export type ButtonVariantName = keyof ButtonVariants extends never ? string : keyof ButtonVariants;
+/** Theme configuration for button styles, variants, and default variant. */
+export interface ThemeButton extends ButtonStyles {
+    defaultVariant?: ButtonVariantName;
+    variants?: ButtonVariantsRecord;
+}
+/**
+ * A resolved breakpoint with its numeric value and a ready-to-use media query
+ * string that targets viewports narrower than this breakpoint.
+ */
+export interface ThemeBreakpoint {
+    /** The breakpoint width in pixels. */
+    value: number;
+    /** A CSS media query matching viewports below this breakpoint, e.g. `"@media (max-width: 599px)"`. */
+    belowMediaQuery: string;
+}
+/**
+ * Responsive breakpoints used by the email layout.
+ *
+ * The `default` breakpoint typically matches the body width, while `mobile`
+ * defines the narrow viewport threshold.
+ */
+export interface ThemeBreakpoints {
+    /** The default breakpoint, usually equal to `sizes.bodyWidth`. */
+    default: ThemeBreakpoint;
+    /**
+     * The mobile breakpoint — the viewport width below which the layout is
+     * considered "mobile".
+     *
+     * When used with `MjmlMailRoot`, this value also controls the MJML
+     * responsive breakpoint (`<mj-breakpoint>`), which determines the viewport
+     * width at which columns stack vertically.
+     */
+    mobile: ThemeBreakpoint;
+}
+/** Numeric size tokens for the email layout. */
+export interface ThemeSizes {
+    /** The width of the email body in pixels. */
+    bodyWidth: number;
+    /** Content indentation (left/right padding) in pixels, supporting per-breakpoint values. */
+    contentIndentation: ResponsiveValue;
+}
+/** Background color tokens for usage through the email layout. */
+export interface ThemeBackgroundColors {
+    body: string;
+    content: string;
+}
+/** Color tokens for usage through the email layout. */
+export interface ThemeColors {
+    background: ThemeBackgroundColors;
+}
+/**
+ * The root theme object that holds all design tokens for `@dextinity/mail-react`.
+ *
+ * Every sub-interface is declared as an `interface` so consumers can
+ * extend the theme at any level via TypeScript module augmentation.
+ */
+export interface Theme {
+    sizes: ThemeSizes;
+    breakpoints: ThemeBreakpoints;
+    text: ThemeText;
+    divider: ThemeDivider;
+    button: ThemeButton;
+    colors: ThemeColors;
+}
+export {};

package/lib/theme/themeTypes.js

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

package/lib/utils/css.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Helper function to enable syntax highlighting & auto-formatting for CSS strings when using certain IDE plugins, e.g. the "styled-components" plugin in VSCode.
+ */
+export declare const css: (strings: TemplateStringsArray, ...rest: unknown[]) => string;

package/lib/utils/css.js

@@ -0,0 +1,4 @@
+/**
+ * Helper function to enable syntax highlighting & auto-formatting for CSS strings when using certain IDE plugins, e.g. the "styled-components" plugin in VSCode.
+ */
+export const css = (strings, ...rest) => String.raw({ raw: strings }, ...rest);

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@dextinity/mail-react",
+  "version": "2.0.0-canary-20260729062014",
+  "description": "Utilities for building HTML emails with React",
+  "license": "BSD-2-Clause",
+  "type": "module",
+  "repository": {
+    "directory": "packages/mail-react",
+    "type": "git",
+    "url": "https://github.com/vivid-planet/comet"
+  },
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client/index.js",
+    "./server": "./lib/server/index.js",
+    "./storybook": "./lib/storybook/index.js"
+  },
+  "sideEffects": false,
+  "files": [
+    "lib/*"
+  ],
+  "dependencies": {
+    "@faire/mjml-react": "^3.5.4",
+    "clsx": "^2.1.1",
+    "mjml": "^4.18.0",
+    "mjml-browser": "^4.18.0",
+    "redraft": "^0.10.2"
+  },
+  "devDependencies": {
+    "@storybook/addon-docs": "^10.3.5",
+    "@storybook/addon-vitest": "10.3.5",
+    "@storybook/react-vite": "^10.3.5",
+    "@types/mjml": "^4.7.4",
+    "@types/mjml-browser": "^4.15.0",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "@vitest/browser": "4.1.8",
+    "@vitest/browser-playwright": "4.1.8",
+    "chokidar-cli": "^3.0.0",
+    "eslint": "^9.39.4",
+    "npm-run-all2": "^8.0.4",
+    "playwright": "^1.49.1",
+    "prettier": "^3.6.2",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "rimraf": "^6.1.2",
+    "storybook": "^10.3.5",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vitest": "^4.1.8",
+    "@dextinity/cli": "2.0.0-canary-20260729062014",
+    "@dextinity/eslint-config": "2.0.0-canary-20260729062014"
+  },
+  "peerDependencies": {
+    "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
+    "storybook": ">=10.0.0"
+  },
+  "peerDependenciesMeta": {
+    "storybook": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "pnpm run clean && pnpm run generate-block-types && tsc -p tsconfig.build.json",
+    "build-storybook": "storybook build",
+    "clean": "rimraf lib 'src/**/*.generated.ts'",
+    "dev": "pnpm run clean && pnpm generate-block-types && tsc --watch",
+    "generate-block-types": "comet generate-block-types",
+    "generate-block-types:watch": "chokidar -s \"**/block-meta.json\" -c \"$npm_execpath generate-block-types\"",
+    "lint": "pnpm generate-block-types && run-p lint:prettier lint:eslint lint:tsc",
+    "lint:ci": "pnpm run lint",
+    "lint:eslint": "eslint --max-warnings 0 src/ '**/*.json' --no-warn-ignored",
+    "lint:fix": "run-p lint:fix:eslint lint:fix:prettier",
+    "lint:fix:eslint": "pnpm run lint:eslint --fix",
+    "lint:fix:prettier": "pnpm run lint:prettier --write",
+    "lint:prettier": "pnpm exec prettier --check '*.{ts,js,json,md,yml,yaml}'",
+    "lint:tsc": "tsc",
+    "storybook": "storybook dev -p 6066 --no-open",
+    "test": "pnpm run test:unit && pnpm run test:storybook",
+    "test:storybook": "vitest --run --project storybook --outputFile.junit=./junit-storybook.xml",
+    "test:unit": "vitest --run --project unit --outputFile.junit=./junit-unit.xml",
+    "test:watch": "vitest --watch"
+  }
+}