npm - better-svelte-email - Versions diffs - 0.3.5 → 1.0.0-beta.0 - Mend

better-svelte-email 0.3.5 → 1.0.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (56) hide show

package/dist/render/index.js ADDED Viewed

@@ -0,0 +1,138 @@
+import { render as svelteRender } from 'svelte/server';
+import { parse, serialize } from 'parse5';
+import { walk } from './utils/html/walk.js';
+import { setupTailwind } from './utils/tailwindcss/setup-tailwind.js';
+import { sanitizeStyleSheet } from './utils/css/sanitize-stylesheet.js';
+import { extractRulesPerClass } from './utils/css/extract-rules-per-class.js';
+import { getCustomProperties } from './utils/css/get-custom-properties.js';
+import { generate, List } from 'css-tree';
+import { sanitizeNonInlinableRules } from './utils/css/sanitize-non-inlinable-rules.js';
+import { addInlinedStylesToElement } from './utils/tailwindcss/add-inlined-styles-to-element.js';
+import { isValidNode } from './utils/html/is-valid-node.js';
+import { removeAttributesFunctions } from './utils/html/remove-attributes-functions.js';
+import { convert } from 'html-to-text';
+/**
+ * Email renderer that converts Svelte components to email-safe HTML with inlined Tailwind styles.
+ *
+ * @example
+ * ```ts
+ * import Renderer from 'better-svelte-email/renderer';
+ * import EmailComponent from './email.svelte';
+ *
+ * const renderer = new Renderer({
+ *   theme: {
+ *     extend: {
+ *       colors: {
+ *         brand: '#FF3E00'
+ *       }
+ *     }
+ *   }
+ * });
+ *
+ * const html = await renderer.render(EmailComponent, {
+ *   props: { name: 'John' }
+ * });
+ * ```
+ */
+export default class Renderer {
+    tailwindConfig;
+    constructor(tailwindConfig = {}) {
+        this.tailwindConfig = tailwindConfig;
+    }
+    /**
+     * Renders a Svelte component to email-safe HTML with inlined Tailwind CSS.
+     *
+     * Automatically:
+     * - Converts Tailwind classes to inline styles
+     * - Injects media queries into `<head>` for responsive classes
+     * - Replaces DOCTYPE with XHTML 1.0 Transitional
+     * - Removes comments and Svelte artifacts
+     *
+     * @param component - The Svelte component to render
+     * @param options - Render options including props, context, and idPrefix
+     * @returns Email-safe HTML string
+     *
+     * @example
+     * ```ts
+     * const html = await renderer.render(EmailComponent, {
+     *   props: { username: 'john_doe', resetUrl: 'https://...' }
+     * });
+     * ```
+     */
+    render = async (component, options) => {
+        const { body } = svelteRender(component, options);
+        let ast = parse(body);
+        ast = removeAttributesFunctions(ast);
+        let classesUsed = [];
+        const tailwindSetup = await setupTailwind(this.tailwindConfig);
+        walk(ast, (node) => {
+            if (isValidNode(node)) {
+                const classAttr = node.attrs?.find((attr) => attr.name === 'class');
+                if (classAttr && classAttr.value) {
+                    const classes = classAttr.value.split(/\s+/).filter(Boolean);
+                    classesUsed = [...classesUsed, ...classes];
+                    tailwindSetup.addUtilities(classes);
+                }
+            }
+            return node;
+        });
+        const styleSheet = tailwindSetup.getStyleSheet();
+        sanitizeStyleSheet(styleSheet);
+        const { inlinable: inlinableRules, nonInlinable: nonInlinableRules } = extractRulesPerClass(styleSheet, classesUsed);
+        const customProperties = getCustomProperties(styleSheet);
+        const nonInlineStyles = {
+            type: 'StyleSheet',
+            children: new List().fromArray(Array.from(nonInlinableRules.values()))
+        };
+        sanitizeNonInlinableRules(nonInlineStyles);
+        const hasNonInlineStylesToApply = nonInlinableRules.size > 0;
+        let appliedNonInlineStyles = false;
+        let hasHead = false;
+        const unknownClasses = [];
+        ast = walk(ast, (node) => {
+            if (isValidNode(node)) {
+                const elementWithInlinedStyles = addInlinedStylesToElement(node, inlinableRules, nonInlinableRules, customProperties, unknownClasses);
+                if (node.nodeName === 'head') {
+                    hasHead = true;
+                }
+                return elementWithInlinedStyles;
+            }
+            return node;
+        });
+        let serialized = serialize(ast);
+        if (unknownClasses.length > 0) {
+            console.warn(`[better-svelte-email] You are using the following classes that were not recognized: ${unknownClasses.join(' ')}.`);
+        }
+        if (hasHead && hasNonInlineStylesToApply) {
+            appliedNonInlineStyles = true;
+            serialized = serialized.replace('<head>', '<head>' + '<style>' + generate(nonInlineStyles) + '</style>');
+        }
+        if (hasNonInlineStylesToApply && !appliedNonInlineStyles) {
+            throw new Error(`You are trying to use the following Tailwind classes that cannot be inlined: ${Array.from(nonInlinableRules.keys()).join(' ')}.
+For the media queries to work properly on rendering, they need to be added into a <style> tag inside of a <head> tag,
+the render function tried finding a <head> element but just wasn't able to find it.
+Make sure that you have a <head> element at any depth.
+This can also be our <Head> component.
+If you do already have a <head> element at some depth,
+please file a bug https://github.com/Konixy/better-svelte-email/issues/new?assignees=&labels=bug&projects=.`);
+        }
+        // Replace various DOCTYPE formats with XHTML 1.0 Transitional
+        serialized = serialized.replace(/<!DOCTYPE\s+html[^>]*>/i, '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">');
+        return serialized;
+    };
+}
+/**
+ * Render HTML as plain text
+ * @param markup - HTML string
+ * @returns Plain text string
+ */
+export const toPlainText = (markup) => {
+    return convert(markup, {
+        selectors: [
+            { selector: 'img', format: 'skip' },
+            { selector: '#__better-svelte-email-preview', format: 'skip' }
+        ]
+    });
+};

package/dist/render/utils/compatibility/sanitize-class-name.d.ts ADDED Viewed

@@ -0,0 +1,7 @@
+/**
+ * Replaces special characters to avoid problems on email clients.
+ *
+ * @param className - This should not come with any escaped charcters, it should come the same
+ * as is on the `className` attribute on React elements.
+ */
+export declare function sanitizeClassName(className: string): string;

package/dist/render/utils/compatibility/sanitize-class-name.js ADDED Viewed

@@ -0,0 +1,35 @@
+const digitToNameMap = {
+    '0': 'zero',
+    '1': 'one',
+    '2': 'two',
+    '3': 'three',
+    '4': 'four',
+    '5': 'five',
+    '6': 'six',
+    '7': 'seven',
+    '8': 'eight',
+    '9': 'nine'
+};
+/**
+ * Replaces special characters to avoid problems on email clients.
+ *
+ * @param className - This should not come with any escaped charcters, it should come the same
+ * as is on the `className` attribute on React elements.
+ */
+export function sanitizeClassName(className) {
+    return className
+        .replaceAll('+', 'plus')
+        .replaceAll('[', '')
+        .replaceAll('%', 'pc')
+        .replaceAll(']', '')
+        .replaceAll('(', '')
+        .replaceAll(')', '')
+        .replaceAll('!', 'imprtnt')
+        .replaceAll('>', 'gt')
+        .replaceAll('<', 'lt')
+        .replaceAll('=', 'eq')
+        .replace(/^[0-9]/, (digit) => {
+        return digitToNameMap[digit];
+    })
+        .replace(/[^a-zA-Z0-9\-_]/g, '_');
+}

package/dist/render/utils/css/extract-rules-per-class.d.ts ADDED Viewed

@@ -0,0 +1,5 @@
+import { type CssNode, type Rule } from 'css-tree';
+export declare function extractRulesPerClass(root: CssNode, classes: string[]): {
+    inlinable: Map<string, Rule>;
+    nonInlinable: Map<string, Rule>;
+};

package/dist/render/utils/css/extract-rules-per-class.js ADDED Viewed

@@ -0,0 +1,37 @@
+import { string, walk } from 'css-tree';
+import { isRuleInlinable } from './is-rule-inlinable.js';
+export function extractRulesPerClass(root, classes) {
+    const classSet = new Set(classes);
+    const inlinableRules = new Map();
+    const nonInlinableRules = new Map();
+    walk(root, {
+        visit: 'Rule',
+        enter(rule) {
+            const selectorClasses = [];
+            walk(rule, {
+                visit: 'ClassSelector',
+                enter(classSelector) {
+                    selectorClasses.push(string.decode(classSelector.name));
+                }
+            });
+            if (isRuleInlinable(rule)) {
+                for (const className of selectorClasses) {
+                    if (classSet.has(className)) {
+                        inlinableRules.set(className, rule);
+                    }
+                }
+            }
+            else {
+                for (const className of selectorClasses) {
+                    if (classSet.has(className)) {
+                        nonInlinableRules.set(className, rule);
+                    }
+                }
+            }
+        }
+    });
+    return {
+        inlinable: inlinableRules,
+        nonInlinable: nonInlinableRules
+    };
+}

package/dist/render/utils/css/get-custom-properties.d.ts ADDED Viewed

@@ -0,0 +1,8 @@
+import { type CssNode, type Declaration } from 'css-tree';
+export interface CustomProperty {
+    syntax?: Declaration;
+    inherits?: Declaration;
+    initialValue?: Declaration;
+}
+export type CustomProperties = Map<string, CustomProperty>;
+export declare function getCustomProperties(node: CssNode): Map<string, CustomProperty>;

package/dist/render/utils/css/get-custom-properties.js ADDED Viewed

@@ -0,0 +1,37 @@
+import { generate, walk } from 'css-tree';
+export function getCustomProperties(node) {
+    const customProperties = new Map();
+    walk(node, {
+        visit: 'Atrule',
+        enter(atrule) {
+            if (atrule.name === 'property' && atrule.prelude) {
+                const prelude = generate(atrule.prelude);
+                if (prelude.startsWith('--')) {
+                    let syntax;
+                    let inherits;
+                    let initialValue;
+                    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/dist/render/utils/css/is-rule-inlinable.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ import { type Rule } from 'css-tree';
2	+ export declare function isRuleInlinable(rule: Rule): boolean;

package/dist/render/utils/css/is-rule-inlinable.js ADDED Viewed

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

package/dist/render/utils/css/make-inline-styles-for.d.ts ADDED Viewed

@@ -0,0 +1,3 @@
+import { type CssNode } from 'css-tree';
+import type { CustomProperties } from './get-custom-properties.js';
+export declare function makeInlineStylesFor(inlinableRules: CssNode[], customProperties: CustomProperties): string;

package/dist/render/utils/css/make-inline-styles-for.js ADDED Viewed

@@ -0,0 +1,57 @@
+import { generate, walk } from 'css-tree';
+import { unwrapValue } from './unwrap-value.js';
+export function makeInlineStylesFor(inlinableRules, customProperties) {
+    let styles = '';
+    const localVariableDeclarations = new Map();
+    for (const rule of inlinableRules) {
+        walk(rule, {
+            visit: 'Declaration',
+            enter(declaration) {
+                if (declaration.property.startsWith('--')) {
+                    localVariableDeclarations.set(declaration.property, declaration);
+                }
+            }
+        });
+    }
+    for (const rule of inlinableRules) {
+        walk(rule, {
+            visit: 'Function',
+            enter(func, funcParentListItem) {
+                if (func.name === 'var') {
+                    let variableName;
+                    walk(func, {
+                        visit: 'Identifier',
+                        enter(identifier) {
+                            variableName = identifier.name;
+                            return this.break;
+                        }
+                    });
+                    if (variableName) {
+                        const definition = localVariableDeclarations.get(variableName);
+                        if (definition) {
+                            funcParentListItem.data = unwrapValue(definition.value);
+                        }
+                        else {
+                            // For most variables tailwindcss defines, they also define a custom
+                            // property for them with an initial value that we can inline here
+                            const customProperty = customProperties.get(variableName);
+                            if (customProperty?.initialValue) {
+                                funcParentListItem.data = unwrapValue(customProperty.initialValue.value);
+                            }
+                        }
+                    }
+                }
+            }
+        });
+        walk(rule, {
+            visit: 'Declaration',
+            enter(declaration) {
+                if (declaration.property.startsWith('--')) {
+                    return;
+                }
+                styles += `${declaration.property}: ${generate(declaration.value)} ${declaration.important ? '!important' : ''};`;
+            }
+        });
+    }
+    return styles;
+}

package/dist/render/utils/css/resolve-all-css-variables.d.ts ADDED Viewed

@@ -0,0 +1,8 @@
+import { type CssNode, type Declaration } from 'css-tree';
+export interface VariableDefinition {
+    declaration: Declaration;
+    path: CssNode[];
+    variableName: string;
+    definition: string;
+}
+export declare function resolveAllCssVariables(node: CssNode): void;

package/dist/render/utils/css/resolve-all-css-variables.js ADDED Viewed

@@ -0,0 +1,123 @@
+import { generate, parse, walk } from 'css-tree';
+function doSelectorsIntersect(first, second) {
+    const firstStringified = generate(first);
+    const secondStringified = generate(second);
+    if (firstStringified === secondStringified) {
+        return true;
+    }
+    let hasSomeUniversal = false;
+    const walker = (node, _parentListItem, parentList) => {
+        if (hasSomeUniversal)
+            return;
+        if (node.type === 'PseudoClassSelector' && node.name === 'root') {
+            hasSomeUniversal = true;
+        }
+        if (node.type === 'TypeSelector' && node.name === '*' && parentList.size === 1) {
+            hasSomeUniversal = true;
+        }
+    };
+    walk(first, walker);
+    walk(second, walker);
+    if (hasSomeUniversal) {
+        return true;
+    }
+    return false;
+}
+export function resolveAllCssVariables(node) {
+    const variableDefinitions = new Set();
+    const variableUses = new Set();
+    const path = [];
+    walk(node, {
+        leave() {
+            path.shift();
+        },
+        enter(node) {
+            if (node.type === 'Declaration') {
+                const declaration = node;
+                // Ignores @layer (properties) { ... } to avoid variable resolution conflicts
+                if (path.some((ancestor) => ancestor.type === 'Atrule' &&
+                    ancestor.name === 'layer' &&
+                    ancestor.prelude !== null &&
+                    generate(ancestor.prelude).includes('properties'))) {
+                    path.unshift(node);
+                    return;
+                }
+                if (/--[\S]+/.test(declaration.property)) {
+                    variableDefinitions.add({
+                        declaration,
+                        path: [...path],
+                        variableName: declaration.property,
+                        definition: generate(declaration.value)
+                    });
+                }
+                else {
+                    function parseVariableUsesFrom(node) {
+                        walk(node, {
+                            visit: 'Function',
+                            enter(funcNode) {
+                                if (funcNode.name === 'var') {
+                                    const children = funcNode.children.toArray();
+                                    const name = generate(children[0]);
+                                    const fallback =
+                                    // The second argument should be an "," Operator Node,
+                                    // such that the actual fallback is only in the third argument
+                                    children[2] ? generate(children[2]) : undefined;
+                                    variableUses.add({
+                                        declaration,
+                                        path: [...path],
+                                        fallback,
+                                        variableName: name,
+                                        raw: generate(funcNode)
+                                    });
+                                    if (fallback?.includes('var(')) {
+                                        const parsedFallback = parse(fallback, {
+                                            context: 'value'
+                                        });
+                                        parseVariableUsesFrom(parsedFallback);
+                                    }
+                                }
+                            }
+                        });
+                    }
+                    parseVariableUsesFrom(declaration.value);
+                }
+            }
+            path.unshift(node);
+        }
+    });
+    for (const use of variableUses) {
+        let hasReplaced = false;
+        for (const definition of variableDefinitions) {
+            if (use.variableName !== definition.variableName) {
+                continue;
+            }
+            if (use.path[0]?.type === 'Block' &&
+                use.path[1]?.type === 'Atrule' &&
+                use.path[2]?.type === 'Block' &&
+                use.path[3]?.type === 'Rule' &&
+                definition.path[0].type === 'Block' &&
+                definition.path[1].type === 'Rule' &&
+                doSelectorsIntersect(use.path[3].prelude, definition.path[1].prelude)) {
+                use.declaration.value = parse(generate(use.declaration.value).replaceAll(use.raw, definition.definition), {
+                    context: 'value'
+                });
+                hasReplaced = true;
+                break;
+            }
+            if (use.path[0]?.type === 'Block' &&
+                use.path[1]?.type === 'Rule' &&
+                definition.path[0]?.type === 'Block' &&
+                definition.path[1]?.type === 'Rule' &&
+                doSelectorsIntersect(use.path[1].prelude, definition.path[1].prelude)) {
+                use.declaration.value = parse(generate(use.declaration.value).replaceAll(use.raw, definition.definition), {
+                    context: 'value'
+                });
+                hasReplaced = true;
+                break;
+            }
+        }
+        if (!hasReplaced && use.fallback) {
+            use.declaration.value = parse(generate(use.declaration.value).replaceAll(use.raw, use.fallback), { context: 'value' });
+        }
+    }
+}

package/dist/render/utils/css/resolve-calc-expressions.d.ts ADDED Viewed

@@ -0,0 +1,5 @@
+import { type CssNode } from 'css-tree';
+/**
+ * Intentionally only resolves `*` and `/` operations without dealing with parenthesis, because this is the only thing required to run Tailwind v4
+ */
+export declare function resolveCalcExpressions(node: CssNode): void;

package/dist/render/utils/css/resolve-calc-expressions.js ADDED Viewed

@@ -0,0 +1,126 @@
+import { walk } from 'css-tree';
+/**
+ * Intentionally only resolves `*` and `/` operations without dealing with parenthesis, because this is the only thing required to run Tailwind v4
+ */
+export function resolveCalcExpressions(node) {
+    walk(node, {
+        visit: 'Function',
+        enter(func, funcListItem) {
+            if (func.name === 'calc') {
+                /*
+          [
+            { type: 'Dimension', loc: null, value: '0.25', unit: 'rem' },
+            { type: 'Operator', loc: null, value: '*' },
+            { type: 'Number', loc: null, value: '2' }
+            { type: 'Percentage', loc: null, value: '2' }
+          ]
+        */
+                func.children.forEach((child, item) => {
+                    const left = item.prev;
+                    const right = item.next;
+                    if (left &&
+                        right &&
+                        child.type === 'Operator' &&
+                        (left.data.type === 'Dimension' ||
+                            left.data.type === 'Number' ||
+                            left.data.type === 'Percentage') &&
+                        (right.data.type === 'Dimension' ||
+                            right.data.type === 'Number' ||
+                            right.data.type === 'Percentage')) {
+                        if (child.value === '*' || child.value === '/') {
+                            const value = (() => {
+                                if (child.value === '*') {
+                                    return String(Number.parseFloat(left.data.value) * Number.parseFloat(right.data.value));
+                                }
+                                if (right.data.value === '0') {
+                                    return '0';
+                                }
+                                return String(Number.parseFloat(left.data.value) / Number.parseFloat(right.data.value));
+                            })();
+                            if (left.data.type === 'Dimension' && right.data.type === 'Number') {
+                                item.data = {
+                                    type: 'Dimension',
+                                    unit: left.data.unit,
+                                    value
+                                };
+                                func.children.remove(left);
+                                func.children.remove(right);
+                            }
+                            else if (left.data.type === 'Number' && right.data.type === 'Dimension') {
+                                item.data = {
+                                    type: 'Dimension',
+                                    unit: right.data.unit,
+                                    value
+                                };
+                                func.children.remove(left);
+                                func.children.remove(right);
+                            }
+                            else if (left.data.type === 'Number' && right.data.type === 'Number') {
+                                item.data = {
+                                    type: 'Number',
+                                    value
+                                };
+                                func.children.remove(left);
+                                func.children.remove(right);
+                            }
+                            else if (left.data.type === 'Dimension' &&
+                                right.data.type === 'Dimension' &&
+                                left.data.unit === right.data.unit) {
+                                if (child.value === '/') {
+                                    item.data = {
+                                        type: 'Number',
+                                        value
+                                    };
+                                }
+                                else {
+                                    item.data = {
+                                        type: 'Dimension',
+                                        unit: left.data.unit,
+                                        value
+                                    };
+                                }
+                                func.children.remove(left);
+                                func.children.remove(right);
+                            }
+                            else if (left.data.type === 'Percentage' && right.data.type === 'Number') {
+                                item.data = {
+                                    type: 'Percentage',
+                                    value
+                                };
+                                func.children.remove(left);
+                                func.children.remove(right);
+                            }
+                            else if (left.data.type === 'Number' && right.data.type === 'Percentage') {
+                                item.data = {
+                                    type: 'Percentage',
+                                    value
+                                };
+                                func.children.remove(left);
+                                func.children.remove(right);
+                            }
+                            else if (left.data.type === 'Percentage' && right.data.type === 'Percentage') {
+                                if (child.value === '/') {
+                                    item.data = {
+                                        type: 'Number',
+                                        value
+                                    };
+                                }
+                                else {
+                                    item.data = {
+                                        type: 'Percentage',
+                                        value
+                                    };
+                                }
+                                func.children.remove(left);
+                                func.children.remove(right);
+                            }
+                        }
+                    }
+                });
+                if (func.children.size === 1 && func.children.first) {
+                    funcListItem.data = func.children.first;
+                }
+            }
+        }
+    });
+}

package/dist/render/utils/css/sanitize-declarations.d.ts ADDED Viewed

@@ -0,0 +1,15 @@
+import { type CssNode } from 'css-tree';
+/**
+ * Meant to do all the things necessary, in a per-declaration basis, to have the best email client
+ * support possible.
+ *
+ * Here's the transformations it does so far:
+ * - convert all `rgb` with space-based syntax into a comma based one;
+ * - convert all `oklch` values into `rgb`;
+ * - convert all hex values into `rgb`;
+ * - convert `padding-inline` into `padding-left` and `padding-right`;
+ * - convert `padding-block` into `padding-top` and `padding-bottom`;
+ * - convert `margin-inline` into `margin-left` and `margin-right`;
+ * - convert `margin-block` into `margin-top` and `margin-bottom`.
+ */
+export declare function sanitizeDeclarations(nodeContainingDeclarations: CssNode): void;