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

package/lib/theme/createTheme.test.js

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import { createTheme } from "./createTheme.js";
+import { getDefaultFromResponsiveValue, getResponsiveOverrides } from "./responsiveValue.js";
+describe("createTheme text", () => {
+    it("includes default text values when no overrides given", () => {
+        const theme = createTheme();
+        expect(theme.text.fontFamily).toBe("Arial, sans-serif");
+        expect(theme.text.fontSize).toBe("16px");
+        expect(theme.text.lineHeight).toBe("20px");
+        expect(theme.text.bottomSpacing).toBe("16px");
+    });
+    it("shallow-merges text overrides with defaults", () => {
+        const theme = createTheme({ text: { fontFamily: "Georgia, serif", fontSize: "18px" } });
+        expect(theme.text.fontFamily).toBe("Georgia, serif");
+        expect(theme.text.fontSize).toBe("18px");
+        expect(theme.text.lineHeight).toBe("20px");
+        expect(theme.text.bottomSpacing).toBe("16px");
+    });
+    it("passes through variant definitions", () => {
+        const theme = createTheme({
+            text: {
+                variants: {
+                    heading: { fontSize: { default: "32px", mobile: "24px" } },
+                },
+            },
+        });
+        expect(theme.text.variants).toBeDefined();
+        expect(theme.text.variants?.heading).toEqual({ fontSize: { default: "32px", mobile: "24px" } });
+    });
+    it("does not set defaultVariant or variants by default", () => {
+        const theme = createTheme();
+        expect(theme.text.defaultVariant).toBeUndefined();
+        expect(theme.text.variants).toBeUndefined();
+    });
+});
+describe("createTheme contentIndentation", () => {
+    it("has default contentIndentation with responsive mobile value", () => {
+        const theme = createTheme();
+        expect(getDefaultFromResponsiveValue(theme.sizes.contentIndentation)).toBe(32);
+        expect(getResponsiveOverrides(theme.sizes.contentIndentation)).toContainEqual({ breakpointKey: "mobile", value: 16 });
+    });
+    it("allows overriding contentIndentation with a plain number", () => {
+        const theme = createTheme({ sizes: { contentIndentation: 30 } });
+        expect(getDefaultFromResponsiveValue(theme.sizes.contentIndentation)).toBe(30);
+        expect(getResponsiveOverrides(theme.sizes.contentIndentation)).toEqual([]);
+    });
+    it("allows overriding contentIndentation with an object", () => {
+        const theme = createTheme({ sizes: { contentIndentation: { default: 30, mobile: 15 } } });
+        expect(getDefaultFromResponsiveValue(theme.sizes.contentIndentation)).toBe(30);
+        expect(getResponsiveOverrides(theme.sizes.contentIndentation)).toContainEqual({ breakpointKey: "mobile", value: 15 });
+    });
+});

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,23 @@
+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",
+    },
+    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,33 @@
+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/responsiveValue.test.d.ts

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

package/lib/theme/responsiveValue.test.js

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import { getDefaultFromResponsiveValue, getDefaultOrUndefined, getResponsiveOverrides } from "./responsiveValue.js";
+describe("getDefaultFromResponsiveValue", () => {
+    it("returns the value when given a plain number", () => {
+        expect(getDefaultFromResponsiveValue(20)).toBe(20);
+    });
+    it("returns the default property from an object", () => {
+        expect(getDefaultFromResponsiveValue({ default: 20, mobile: 10 })).toBe(20);
+    });
+    it("returns the default property when only default is present", () => {
+        expect(getDefaultFromResponsiveValue({ default: 42 })).toBe(42);
+    });
+    it("works with string type", () => {
+        expect(getDefaultFromResponsiveValue({ default: "24px", mobile: "20px" })).toBe("24px");
+    });
+    it("returns a plain string value", () => {
+        expect(getDefaultFromResponsiveValue("24px")).toBe("24px");
+    });
+});
+describe("getResponsiveOverrides", () => {
+    it("returns an empty array for a plain number", () => {
+        expect(getResponsiveOverrides(20)).toEqual([]);
+    });
+    it("returns an empty array for an object with only default", () => {
+        expect(getResponsiveOverrides({ default: 42 })).toEqual([]);
+    });
+    it("returns overrides for non-default keys", () => {
+        const result = getResponsiveOverrides({ default: 20, mobile: 10 });
+        expect(result).toEqual([{ breakpointKey: "mobile", value: 10 }]);
+    });
+    it("returns multiple overrides for multiple breakpoint keys", () => {
+        const value = { default: 30, mobile: 10 };
+        const result = getResponsiveOverrides(value);
+        expect(result).toContainEqual({ breakpointKey: "mobile", value: 10 });
+        expect(result).not.toContainEqual(expect.objectContaining({ breakpointKey: "default" }));
+    });
+    it("never includes the default key in overrides", () => {
+        const result = getResponsiveOverrides({ default: 20, mobile: 10 });
+        expect(result.every((o) => o.breakpointKey !== "default")).toBe(true);
+    });
+    it("works with string type", () => {
+        const result = getResponsiveOverrides({ default: "24px", mobile: "20px" });
+        expect(result).toEqual([{ breakpointKey: "mobile", value: "20px" }]);
+    });
+});
+describe("getDefaultOrUndefined", () => {
+    it("returns undefined when given undefined", () => {
+        expect(getDefaultOrUndefined(undefined)).toBeUndefined();
+    });
+    it("returns the value when given a plain value", () => {
+        expect(getDefaultOrUndefined(20)).toBe(20);
+    });
+    it("returns the default property from an object", () => {
+        expect(getDefaultOrUndefined({ default: 20, mobile: 10 })).toBe(20);
+    });
+    it("works with string type", () => {
+        expect(getDefaultOrUndefined("24px")).toBe("24px");
+    });
+    it("returns default from a string responsive object", () => {
+        expect(getDefaultOrUndefined({ default: "32px", mobile: "24px" })).toBe("32px");
+    });
+});

package/lib/theme/themeTypes.d.ts

@@ -0,0 +1,106 @@
+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 "@comet/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;
+}
+/**
+ * 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 `@comet/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;
+    colors: ThemeColors;
+}
+export {};

package/lib/theme/themeTypes.js

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

package/lib/utils/css.test.d.ts

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

package/lib/utils/css.test.js

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { css } from "./css.js";
+describe("css tagged-template helper", () => {
+    it("returns static template text exactly", () => {
+        const result = css `
+            color: red;
+            font-size: 16px;
+        `;
+        expect(result).toBe(`
+            color: red;
+            font-size: 16px;
+        `);
+    });
+    it("resolves interpolated values correctly", () => {
+        const color = "blue";
+        const size = 14;
+        const result = css `
+            color: ${color};
+            font-size: ${size}px;
+        `;
+        expect(result).toBe(`
+            color: blue;
+            font-size: 14px;
+        `);
+    });
+});

package/package.json

@@ -1,22 +1,30 @@
 {
   "name": "@comet/mail-react",
-  "version": "9.0.0-beta.0",
+  "version": "9.0.0-beta.2",
   "description": "Utilities for building HTML emails with React",
   "license": "BSD-2-Clause",
   "type": "module",
   "exports": {
-    ".": {
-      "types": "./lib/index.d.ts",
-      "default": "./lib/index.js"
-    }
+    ".": "./lib/index.js",
+    "./client": "./lib/client/index.js",
+    "./server": "./lib/server/index.js",
+    "./storybook": "./lib/storybook/index.js"
   },
   "files": [
     "lib/*"
   ],
   "dependencies": {
-    "@faire/mjml-react": "^3.5.3"
+    "@faire/mjml-react": "^3.5.3",
+    "clsx": "^2.1.1",
+    "mjml": "^4.18.0",
+    "mjml-browser": "^4.18.0"
   },
   "devDependencies": {
+    "@fission-ai/openspec": "^1.2.0",
+    "@storybook/addon-docs": "^10.3.1",
+    "@storybook/react-vite": "^10.3.1",
+    "@types/mjml": "^4.7.4",
+    "@types/mjml-browser": "^4.15.0",
     "@types/react": "^19.2.10",
     "@types/react-dom": "^19.2.3",
     "chokidar-cli": "^3.0.0",
@@ -26,12 +34,20 @@
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "rimraf": "^6.1.2",
+    "storybook": "^10.3.1",
     "typescript": "^5.9.3",
-    "@comet/cli": "9.0.0-beta.0",
-    "@comet/eslint-config": "9.0.0-beta.0"
+    "vitest": "^4.0.16",
+    "@comet/cli": "9.0.0-beta.2",
+    "@comet/eslint-config": "9.0.0-beta.2"
   },
   "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0"
+    "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
+    "storybook": ">=10.0.0"
+  },
+  "peerDependenciesMeta": {
+    "storybook": {
+      "optional": true
+    }
   },
   "engines": {
     "node": ">=22.0.0"
@@ -42,14 +58,22 @@
   },
   "scripts": {
     "build": "pnpm run clean && pnpm run generate-block-types && tsc",
+    "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: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"
+    "lint:tsc": "tsc",
+    "openspec:install-skills": "openspec init --tools github-copilot,cursor,claude",
+    "storybook": "storybook dev -p 6066 --no-open",
+    "test": "vitest --run",
+    "test:watch": "vitest --watch"
   }
 }