@depup/react-email 5.2.10-depup.1 → 6.9.1-depup.0

package/src/components/tailwind/utils/css/downlevel-for-email-clients.ts

@@ -0,0 +1,245 @@
+/**
+ * Downlevels modern CSS features that email clients don't support,
+ * operating on a css-tree StyleSheet AST.
+ *
+ * 1. CSS Nesting: unnests @media rules from inside selectors
+ *    `.sm_p-4{@media (min-width:40rem){padding:1rem!important}}`
+ *    → `@media (min-width:40rem){.sm_p-4{padding:1rem!important}}`
+ *
+ * 2. Media Queries Level 4 range syntax → legacy min-width/max-width
+ *    `(width>=40rem)` → `(min-width:40rem)`
+ *
+ * Gmail, Outlook, Yahoo, and most email clients don't support either feature.
+ * See: https://www.caniemail.com/features/css-at-media/
+ *      https://www.caniemail.com/features/css-nesting/
+ */
+
+import {
+  type Atrule,
+  type CssNode,
+  clone,
+  type Feature,
+  type FeatureRange,
+  List,
+  type ListItem,
+  type Rule,
+  type StyleSheet,
+  walk,
+} from 'css-tree';
+import { NON_INLINABLE_ATRULES } from './constants.js';
+
+/**
+ * css-tree 3.x introduced new AST node types for query-related at-rules that
+ * `@types/css-tree` (still on 2.x at the time of writing) doesn't expose.
+ * Augmenting the module here lets the rest of this file work with strong
+ * types instead of scattering `as` casts everywhere.
+ *
+ * - `FeatureRange` is what the parser emits for Media Queries Level 4 range
+ *   syntax: `(width >= 40rem)`.
+ * - `Feature` is the legacy form (`(min-width: 40rem)`) we construct as the
+ *   downleveled output.
+ *
+ * Note: we cannot extend the `CssNode` union itself (it's a `type` alias, not
+ * an interface), so two narrow casts remain in this file:
+ *   1. Widening `node` inside `walk()` so we can narrow against
+ *      `FeatureRange.type` (`CssNode` doesn't list `'FeatureRange'`).
+ *   2. Assigning a constructed `Feature` back to `ListItem<CssNode>.data`.
+ *
+ * Both are flagged inline and reference back to this block.
+ *
+ * See:
+ *   https://github.com/csstree/csstree/blob/master/lib/syntax/node/FeatureRange.js
+ *   https://github.com/csstree/csstree/blob/master/lib/syntax/node/Feature.js
+ */
+declare module 'css-tree' {
+  interface FeatureRange extends CssNodeCommon {
+    type: 'FeatureRange';
+    kind: string;
+    left: CssNode;
+    leftComparison: string;
+    middle: CssNode;
+    rightComparison: string | null;
+    right: CssNode | null;
+  }
+
+  interface Feature extends CssNodeCommon {
+    type: 'Feature';
+    kind: string;
+    name: string;
+    value: CssNode | null;
+  }
+}
+
+/**
+ * Unnest @media at-rules from inside regular rules, and downlevel
+ * range media query syntax to legacy min-width/max-width.
+ *
+ * Mutates the stylesheet in place.
+ */
+export function downlevelForEmailClients(styleSheet: StyleSheet): void {
+  unnestMediaQueries(styleSheet);
+  downlevelRangeMediaQueries(styleSheet);
+}
+
+// ---------------------------------------------------------------------------
+// Unnesting
+// ---------------------------------------------------------------------------
+
+interface UnnestTransform {
+  parentRule: Rule;
+  parentItem: ListItem<CssNode>;
+  parentList: List<CssNode>;
+  nestedAtrules: Atrule[];
+  remainingChildren: CssNode[];
+}
+
+/**
+ * Walk the stylesheet and unnest any @media/@supports rules that are nested
+ * inside regular rules. For each, the parent Rule's selector wraps the
+ * at-rule's body.
+ *
+ * Before: `.sm_p-4 { @media (...) { padding: 1rem } }`
+ * After:  `@media (...) { .sm_p-4 { padding: 1rem } }`
+ */
+function unnestMediaQueries(styleSheet: StyleSheet): void {
+  const transforms: UnnestTransform[] = [];
+
+  walk(styleSheet, {
+    visit: 'Rule',
+    enter(rule, item, list) {
+      if (!rule.block || !item) return;
+
+      const nestedAtrules: Atrule[] = [];
+      const remainingChildren: CssNode[] = [];
+
+      rule.block.children.forEach((child) => {
+        if (
+          child.type === 'Atrule' &&
+          NON_INLINABLE_ATRULES.has(child.name.toLowerCase())
+        ) {
+          nestedAtrules.push(child);
+        } else {
+          remainingChildren.push(child);
+        }
+      });
+
+      if (nestedAtrules.length > 0) {
+        transforms.push({
+          parentRule: rule,
+          parentItem: item,
+          parentList: list,
+          nestedAtrules,
+          remainingChildren,
+        });
+      }
+    },
+  });
+
+  // Apply in reverse so list positions stay valid
+  for (let i = transforms.length - 1; i >= 0; i--) {
+    const {
+      parentRule,
+      parentItem,
+      parentList,
+      nestedAtrules,
+      remainingChildren,
+    } = transforms[i]!;
+
+    // Build replacement list: [modified parent rule (if any), unnested @media rules...]
+    const replacements = new List<CssNode>();
+
+    if (remainingChildren.length > 0) {
+      parentRule.block.children = new List<CssNode>().fromArray(
+        remainingChildren,
+      );
+      replacements.appendData(parentRule);
+    }
+
+    for (const atrule of nestedAtrules) {
+      const wrappedRule: Rule = {
+        type: 'Rule',
+        prelude: clone(parentRule.prelude) as Rule['prelude'],
+        block: {
+          type: 'Block',
+          children: atrule.block ? atrule.block.children : new List<CssNode>(),
+        },
+      };
+
+      const newAtrule: Atrule = {
+        type: 'Atrule',
+        name: atrule.name,
+        prelude: atrule.prelude,
+        block: {
+          type: 'Block',
+          children: new List<CssNode>().fromArray([wrappedRule]),
+        },
+      };
+
+      replacements.appendData(newAtrule);
+    }
+
+    // Replace the original rule with the entire list of new nodes
+    parentList.replace(parentItem, replacements);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Range media query downleveling
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk all nodes and downlevel range syntax (`FeatureRange`) inside @media
+ * preludes to legacy `Feature` nodes (`min-width` / `max-width`).
+ */
+function downlevelRangeMediaQueries(styleSheet: StyleSheet): void {
+  const replacements: Array<{
+    item: ListItem<CssNode>;
+    replacement: Feature;
+  }> = [];
+
+  walk(styleSheet, {
+    enter(originalNode, item) {
+      // See module augmentation above: `CssNode` (from @types/css-tree 2.x)
+      // doesn't include `FeatureRange`, so widen here to enable narrowing.
+      const node = originalNode as CssNode | FeatureRange;
+      if (item && node.type === 'FeatureRange') {
+        const replacement = downlevelFeatureRange(node);
+        if (replacement) {
+          replacements.push({ item, replacement });
+        }
+      }
+    },
+  });
+
+  for (const { item, replacement } of replacements) {
+    // See module augmentation above: `Feature` is not part of the `CssNode`
+    // union, so a single cast is required when handing it back to the AST.
+    item.data = replacement as unknown as CssNode;
+  }
+}
+
+/**
+ * Convert a `FeatureRange` node to a `Feature` node (legacy min-/max- syntax).
+ *
+ * For `width >= 40rem`: left=Identifier("width"), leftComparison=">=", middle=Dimension("40","rem")
+ * Result: { type: "Feature", name: "min-width", value: Dimension("40","rem") }
+ */
+function downlevelFeatureRange(range: FeatureRange): Feature | null {
+  if (range.left.type !== 'Identifier') return null;
+
+  let prefix: string;
+  if (range.leftComparison === '>=' || range.leftComparison === '>') {
+    prefix = 'min-';
+  } else if (range.leftComparison === '<=' || range.leftComparison === '<') {
+    prefix = 'max-';
+  } else {
+    return null;
+  }
+
+  return {
+    type: 'Feature',
+    kind: 'media',
+    name: `${prefix}${range.left.name}`,
+    value: range.middle,
+  };
+}

package/src/components/tailwind/utils/css/extract-rules-per-class.spec.ts

@@ -0,0 +1,324 @@
+import { generate, parse, type Rule, type StyleSheet } from 'css-tree';
+import { setupTailwind } from '../tailwindcss/setup-tailwind.js';
+import { extractRulesPerClass } from './extract-rules-per-class.js';
+
+describe('extractRulesPerClass()', async () => {
+  function convertToComparable(
+    map: Map<string, Rule[]>,
+  ): Record<string, string[]> {
+    return Object.fromEntries(
+      map
+        .entries()
+        .map(([k, rules]) => [k, rules.map((rule) => generate(rule))]),
+    );
+  }
+
+  it('works with just inlinable utilities', async () => {
+    const tailwind = await setupTailwind({});
+    const classes = ['text-center', 'bg-red-500'];
+    tailwind.addUtilities(classes);
+
+    const stylesheet = tailwind.getStyleSheet();
+
+    const { inlinable, nonInlinable } = extractRulesPerClass(
+      stylesheet,
+      classes,
+    );
+
+    expect(convertToComparable(inlinable)).toMatchInlineSnapshot(`
+      {
+        "bg-red-500": [
+          ".bg-red-500{background-color:var(--color-red-500)}",
+        ],
+        "text-center": [
+          ".text-center{text-align:center}",
+        ],
+      }
+    `);
+    expect(convertToComparable(nonInlinable)).toMatchInlineSnapshot('{}');
+  });
+
+  it('keeps every rule when a class is defined more than once', async () => {
+    const tailwind = await setupTailwind({
+      config: {
+        plugins: [
+          {
+            handler: (api) => {
+              api.addComponents({
+                '.box': { '@apply rounded-lg bg-white p-4': {} },
+              });
+              api.addComponents({
+                '.box': { '@apply bg-red-500': {} },
+              });
+            },
+          },
+        ],
+      },
+    });
+    const classes = ['box'];
+    tailwind.addUtilities(classes);
+
+    const stylesheet = tailwind.getStyleSheet();
+    const { inlinable } = extractRulesPerClass(stylesheet, classes);
+
+    expect(convertToComparable(inlinable)).toMatchInlineSnapshot(`
+      {
+        "box": [
+          ".box{border-radius:var(--radius-lg);background-color:var(--color-white);padding:calc(var(--spacing)*4)}",
+          ".box{background-color:var(--color-red-500)}",
+        ],
+      }
+    `);
+  });
+
+  it('handles non-inlinable utilities', async () => {
+    const tailwind = await setupTailwind({});
+    const classes = ['lg:w-1/2'];
+    tailwind.addUtilities(classes);
+
+    const stylesheet = tailwind.getStyleSheet();
+
+    const { inlinable, nonInlinable } = extractRulesPerClass(
+      stylesheet,
+      classes,
+    );
+
+    expect(convertToComparable(inlinable)).toMatchInlineSnapshot('{}');
+    expect(convertToComparable(nonInlinable)).toMatchInlineSnapshot(`
+      {
+        "lg:w-1/2": [
+          ".lg\\:w-1\\/2{@media (width>=64rem){width:calc(1/2*100%)}}",
+        ],
+      }
+    `);
+  });
+
+  it('handles a mix of inlinable and non-inlinable utilities', async () => {
+    const tailwind = await setupTailwind({});
+    const classes = [
+      'text-center',
+      'bg-red-500',
+      'some-other-class', // should be ignored
+      'w-full',
+      'lg:w-1/2',
+    ];
+    tailwind.addUtilities(classes);
+
+    const stylesheet = tailwind.getStyleSheet();
+    const { inlinable, nonInlinable } = extractRulesPerClass(
+      stylesheet,
+      classes,
+    );
+    expect(convertToComparable(inlinable)).toMatchInlineSnapshot(`
+      {
+        "bg-red-500": [
+          ".bg-red-500{background-color:var(--color-red-500)}",
+        ],
+        "text-center": [
+          ".text-center{text-align:center}",
+        ],
+        "w-full": [
+          ".w-full{width:100%}",
+        ],
+      }
+    `);
+    expect(convertToComparable(nonInlinable)).toMatchInlineSnapshot(`
+      {
+        "lg:w-1/2": [
+          ".lg\\:w-1\\/2{@media (width>=64rem){width:calc(1/2*100%)}}",
+        ],
+      }
+    `);
+  });
+
+  it('splits mixed rules (base + media) into inlinable base and non-inlinable media', async () => {
+    const tailwind = await setupTailwind({
+      config: {
+        plugins: [
+          {
+            handler: (api) => {
+              api.addUtilities({
+                '.text-body': {
+                  '@apply text-[green] sm:text-[darkgreen]': {},
+                },
+              });
+            },
+          },
+        ],
+      },
+    });
+    const classes = ['text-body'];
+    tailwind.addUtilities(classes);
+
+    const stylesheet = tailwind.getStyleSheet();
+    const { inlinable, nonInlinable } = extractRulesPerClass(
+      stylesheet,
+      classes,
+    );
+
+    expect(convertToComparable(inlinable)).toMatchInlineSnapshot(`
+      {
+        "text-body": [
+          ".text-body{color:green}",
+        ],
+      }
+    `);
+    expect(convertToComparable(nonInlinable)).toMatchInlineSnapshot(`
+      {
+        "text-body": [
+          ".text-body{@media (width>=40rem){color:darkgreen}}",
+        ],
+      }
+    `);
+  });
+
+  it('treats rules with pseudo-selectors as fully non-inlinable', async () => {
+    const tailwind = await setupTailwind({
+      config: {
+        plugins: [
+          {
+            handler: (api) => {
+              api.addUtilities({
+                '.btn:hover': {
+                  color: 'red',
+                },
+              });
+            },
+          },
+        ],
+      },
+    });
+    const classes = ['btn'];
+    tailwind.addUtilities(classes);
+
+    const stylesheet = tailwind.getStyleSheet();
+    const { inlinable, nonInlinable } = extractRulesPerClass(
+      stylesheet,
+      classes,
+    );
+
+    expect(convertToComparable(inlinable)).toMatchInlineSnapshot('{}');
+    expect(convertToComparable(nonInlinable)).toMatchInlineSnapshot(`
+      {
+        "btn": [
+          ".btn{&:hover{color:red}}",
+        ],
+      }
+    `);
+  });
+
+  // Wrapped shape emitted by Tailwind >=4.3.3.
+  // See https://github.com/resend/react-email/issues/3662
+  it('treats @media-wrapped rules (Tailwind >=4.3.3) as non-inlinable', () => {
+    const classes = [
+      'bg-white',
+      'text-black',
+      'dark:bg-black',
+      'dark:text-white',
+    ];
+    const stylesheet = parse(`
+@layer utilities {
+  .bg-white { background-color: rgb(255, 255, 255); }
+  .text-black { color: rgb(0, 0, 0); }
+  @media (prefers-color-scheme: dark) {
+    .dark\\:bg-black { background-color: rgb(0, 0, 0); }
+    .dark\\:text-white { color: rgb(255, 255, 255); }
+  }
+}
+`) as StyleSheet;
+
+    const { inlinable, nonInlinable } = extractRulesPerClass(
+      stylesheet,
+      classes,
+    );
+
+    expect(convertToComparable(inlinable)).toMatchInlineSnapshot(`
+      {
+        "bg-white": [
+          ".bg-white{background-color:rgb(255,255,255)}",
+        ],
+        "text-black": [
+          ".text-black{color:rgb(0,0,0)}",
+        ],
+      }
+    `);
+    expect(convertToComparable(nonInlinable)).toMatchInlineSnapshot(`
+      {
+        "dark:bg-black": [
+          ".dark\\:bg-black{@media (prefers-color-scheme:dark){background-color:rgb(0,0,0)}}",
+        ],
+        "dark:text-white": [
+          ".dark\\:text-white{@media (prefers-color-scheme:dark){color:rgb(255,255,255)}}",
+        ],
+      }
+    `);
+  });
+
+  // Nested shape emitted by Tailwind <=4.3.2; must classify identically.
+  // See https://github.com/resend/react-email/issues/3662
+  it('treats @media-nested rules (Tailwind <=4.3.2) as non-inlinable', () => {
+    const classes = [
+      'bg-white',
+      'text-black',
+      'dark:bg-black',
+      'dark:text-white',
+    ];
+    const stylesheet = parse(`
+@layer utilities {
+  .bg-white { background-color: rgb(255, 255, 255); }
+  .text-black { color: rgb(0, 0, 0); }
+  .dark\\:bg-black { @media (prefers-color-scheme: dark) { background-color: rgb(0, 0, 0); } }
+  .dark\\:text-white { @media (prefers-color-scheme: dark) { color: rgb(255, 255, 255); } }
+}
+`) as StyleSheet;
+
+    const { inlinable, nonInlinable } = extractRulesPerClass(
+      stylesheet,
+      classes,
+    );
+
+    expect(convertToComparable(inlinable)).toMatchInlineSnapshot(`
+      {
+        "bg-white": [
+          ".bg-white{background-color:rgb(255,255,255)}",
+        ],
+        "text-black": [
+          ".text-black{color:rgb(0,0,0)}",
+        ],
+      }
+    `);
+    expect(convertToComparable(nonInlinable)).toMatchInlineSnapshot(`
+      {
+        "dark:bg-black": [
+          ".dark\\:bg-black{@media (prefers-color-scheme:dark){background-color:rgb(0,0,0)}}",
+        ],
+        "dark:text-white": [
+          ".dark\\:text-white{@media (prefers-color-scheme:dark){color:rgb(255,255,255)}}",
+        ],
+      }
+    `);
+  });
+
+  it('does not emit a bare nested rule for group/peer marker classes', async () => {
+    const tailwind = await setupTailwind({});
+    const classes = ['group', 'group-hover:underline'];
+    tailwind.addUtilities(classes);
+
+    const stylesheet = tailwind.getStyleSheet();
+    const { inlinable, nonInlinable } = extractRulesPerClass(
+      stylesheet,
+      classes,
+    );
+
+    // Only the real utility is keyed; the `group` marker must not produce a
+    // duplicate, parentless `&:is(...)` rule.
+    expect(Object.keys(convertToComparable(inlinable))).toEqual([]);
+    expect(convertToComparable(nonInlinable)).toMatchInlineSnapshot(`
+      {
+        "group-hover:underline": [
+          ".group-hover\\:underline{&:is(:where(.group):hover *){@media (hover:hover){text-decoration-line:underline}}}",
+        ],
+      }
+    `);
+  });
+});