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

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

@@ -0,0 +1,244 @@
+/**
+ * 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';
+
+/**
+ * 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' &&
+          (child.name === 'media' || child.name === 'supports')
+        ) {
+          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,232 @@
+import { generate, type Rule } 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}}",
+        ],
+      }
+    `);
+  });
+
+  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}}}",
+        ],
+      }
+    `);
+  });
+});

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

@@ -0,0 +1,76 @@
+import { type CssNode, type Rule, string, walk } from 'css-tree';
+import { isRuleInlinable } from './is-rule-inlinable.js';
+import { splitMixedRule } from './split-mixed-rule.js';
+
+export function extractRulesPerClass(root: CssNode, classes: string[]) {
+  const classSet = new Set(classes);
+
+  // A class can be defined by multiple rules (e.g. a preset and a child config
+  // override), so keep them all to merge instead of the last one clobbering.
+  const inlinableRules = new Map<string, Rule[]>();
+  const nonInlinableRules = new Map<string, Rule[]>();
+
+  const appendRule = (
+    map: Map<string, Rule[]>,
+    className: string,
+    rule: Rule,
+  ) => {
+    const existing = map.get(className);
+    if (existing) {
+      existing.push(rule);
+    } else {
+      map.set(className, [rule]);
+    }
+  };
+
+  walk(root, {
+    visit: 'Rule',
+    enter(rule) {
+      // A nested rule (e.g. group/peer's `&:is(:where(.group):hover *)`) belongs
+      // to its parent utility; processing it standalone emits a bare, parentless
+      // `&` rule into the <style> block, so skip it here.
+      const firstSelector =
+        rule.prelude.type === 'SelectorList'
+          ? rule.prelude.children.first
+          : null;
+      if (
+        firstSelector?.type === 'Selector' &&
+        firstSelector.children.first?.type === 'NestingSelector'
+      ) {
+        return;
+      }
+
+      // Only the prelude names the class that owns the rule; classes referenced
+      // inside the block (e.g. `.group` in `:where(.group)`) must not key it.
+      const selectorClasses: string[] = [];
+      walk(rule.prelude, {
+        visit: 'ClassSelector',
+        enter(classSelector) {
+          selectorClasses.push(string.decode(classSelector.name));
+        },
+      });
+      if (isRuleInlinable(rule)) {
+        for (const className of selectorClasses) {
+          if (classSet.has(className)) {
+            appendRule(inlinableRules, className, rule);
+          }
+        }
+      } else {
+        const { inlinablePart, nonInlinablePart } = splitMixedRule(rule);
+        for (const className of selectorClasses) {
+          if (!classSet.has(className)) continue;
+          if (inlinablePart) {
+            appendRule(inlinableRules, className, inlinablePart);
+          }
+          if (nonInlinablePart) {
+            appendRule(nonInlinableRules, className, nonInlinablePart);
+          }
+        }
+      }
+    },
+  });
+  return {
+    inlinable: inlinableRules,
+    nonInlinable: nonInlinableRules,
+  };
+}

package/src/components/tailwind/utils/css/get-custom-properties.ts

@@ -0,0 +1,49 @@
+import { type CssNode, type Declaration, generate, walk } from 'css-tree';
+
+export interface CustomProperty {
+  syntax?: Declaration;
+  inherits?: Declaration;
+  initialValue?: Declaration;
+}
+
+export type CustomProperties = Map<string, CustomProperty>;
+
+export function getCustomProperties(node: CssNode) {
+  const customProperties = new Map<string, CustomProperty>();
+
+  walk(node, {
+    visit: 'Atrule',
+    enter(atrule) {
+      if (atrule.name === 'property' && atrule.prelude) {
+        const prelude = generate(atrule.prelude);
+        if (prelude.startsWith('--')) {
+          let syntax: Declaration | undefined;
+          let inherits: Declaration | undefined;
+          let initialValue: Declaration | undefined;
+          walk(atrule, {
+            visit: 'Declaration',
+            enter(declaration) {
+              if (declaration.property === 'syntax') {
+                syntax = declaration;
+              }
+              if (declaration.property === 'inherits') {
+                inherits = declaration;
+              }
+              if (declaration.property === 'initial-value') {
+                initialValue = declaration;
+              }
+            },
+          });
+
+          customProperties.set(prelude, {
+            syntax,
+            inherits,
+            initialValue,
+          });
+        }
+      }
+    },
+  });
+
+  return customProperties;
+}

package/src/components/tailwind/utils/css/is-part-inlinable.ts

@@ -0,0 +1,15 @@
+import { type CssNode, find } from 'css-tree';
+
+export function isPartInlinable(part: CssNode): boolean {
+  const hasAtRuleInside = find(part, (node) => node.type === 'Atrule') !== null;
+
+  const hasPseudoSelector =
+    find(
+      part,
+      (node) =>
+        node.type === 'PseudoClassSelector' ||
+        node.type === 'PseudoElementSelector',
+    ) !== null;
+
+  return !hasAtRuleInside && !hasPseudoSelector;
+}

package/src/components/tailwind/utils/css/is-rule-inlinable.ts

@@ -0,0 +1,15 @@
+import { find, type Rule } from 'css-tree';
+
+export function isRuleInlinable(rule: Rule): boolean {
+  const hasAtRuleInside = find(rule, (node) => node.type === 'Atrule') !== null;
+
+  const hasPseudoSelector =
+    find(
+      rule,
+      (node) =>
+        node.type === 'PseudoClassSelector' ||
+        node.type === 'PseudoElementSelector',
+    ) !== null;
+
+  return !hasAtRuleInside && !hasPseudoSelector;
+}