@keycloakify/angular-email 0.0.7 → 1.0.0

package/README.md

@@ -14,6 +14,11 @@ yarn add @keycloakify/angular-email
 
 ## Usage
 
+| Angular | Tailwind CSS | @keycloakify/angular-email | Maintained    |
+| ------- | ------------ | -------------------------- | ------------- |
+| 20      | 4.x+         | 1.x+                       | Yes           |
+| 20      | 3.x+         | 0.x+                       | Bugfixes only |
+
 ### Creating an Email Component
 
 see this [example](https://github.com/keycloakify/angular-email/blob/main/projects/showcase/src/app/app.component.ts)
@@ -49,14 +54,32 @@ export const renderToHtml: RenderToHtml<EmailComponentProps> = (props) => {
 ```sh
 # cmd
 
-export $EMAIL_COMPONENTS_DIR_PATH="src/emails"
-npx keycloakify-angular-email build -p $EMAIL_COMPONENTS_DIR_PATH
+export EMAIL_COMPONENTS_DIR_PATH="src/emails"
+export EMAIL_OUTPUT_DIR_PATH="dist/emails"
+export EMAIL_EXTERNAL_PACKAGES="tailwindcss,@tailwindcss/postcss,postcss,postcss-calc,postcss-custom-properties,postcss-preset-env,postcss-logical"
+
+npx keycloakify-angular-email build -p "$EMAIL_COMPONENTS_DIR_PATH" -o "$EMAIL_OUTPUT_DIR_PATH" -e "$EMAIL_EXTERNAL_PACKAGES"
 ```
 
 NB: use `keycloakify-angular-email build` when you don't need to pass dynamic inputs to your components, otherwise see [Standalone Dynamic Rendering](#standalone-dynamic-rendering)
 
 ### With Keycloakify Emails
 
+```json
+// emails/tsconfig.json
+
+{
+  "extends": "../tsconfig.json",
+  "compileOnSave": false,
+  "compilerOptions": {
+    "outDir": "../out-tsc/emails",
+    "types": []
+  },
+  "files": [],
+  "include": ["*.ts", "**/*.ts"]
+}
+```
+
 ```ts
 // email.component.ts
 ...
@@ -101,7 +124,7 @@ export default defineConfig(({ mode }) => ({
       ...
       postBuild: async (buildContext) => {
         await buildEmailTheme({
-          templatesSrcDirPath: join(import.meta.dirname, '/emails/templates'),
+          templatesSrcDirPath: join(import.meta.dirname, 'emails', 'templates'),
           filterTemplate: (filePath: string) => !!filePath.endsWith('.component.ts'),
           themeNames: buildContext.themeNames,
           keycloakifyBuildDirPath: buildContext.keycloakifyBuildDirPath,
@@ -109,10 +132,10 @@ export default defineConfig(({ mode }) => ({
           cwd: import.meta.dirname,
           esbuild: {
             packages: 'bundle',
-            external: ['juice', 'postcss', 'tailwindcss-v3'],
+            external: ['juice', '...other packages you might use to process css'],
             format: 'esm',
             outExtension: { '.js': '.mjs' },
-            plugins: [angularEsbuildPlugin(import.meta.dirname)],
+            plugins: [angularEsbuildPlugin(join(import.meta.dirname, 'emails'))],
           },
         });
       },
@@ -133,6 +156,7 @@ import { toHTML } from '@keycloakify/angular-email/node';
 toHTML({
   filePath: 'path/to/your.component.ts',
   props: { foo: 'bar' },
+  externals: [],
 })
   .then((html) => {
     console.log(html);
@@ -152,6 +176,7 @@ const { toHTML } = require('@keycloakify/angular-email/node');
 toHTML({
   filePath: 'path/to/your.component.ts',
   props: { foo: 'bar' },
+  externals: [],
 })
   .then((html) => {
     console.log(html);
@@ -185,8 +210,8 @@ type Render<Input extends Record<string, any>> = {
     plainText?: boolean;
     /** format the html output */
     pretty?: boolean;
-    /** tailwind v3 configuration object */
-    tailwindConfig?: Partial<Config>;
+    /** Optional hook to manipulate the extracted CSS. Useful for PostCSS processing */
+    cssProcessor?: (css: string) => Promise<string>;
     /** if you use prefix conventions on signal inputs */
     signalInputsPrefix?: string;
   };
@@ -216,18 +241,52 @@ toHTML<Input extends Record<string, any>>(options: {
     filePath: string;
     props?: Input;
     root?: string;
+    externals?: string[];
 }) => Promise<string>
 ```
 
 ### @keycloakify/angular-email/tailwindcss-preset-email
 
-Just a tailwind v3 preset, inspired by [@maizzle/tailwindcss-preset-email](https://github.com/maizzle/tailwindcss-preset-email)
+Just a tailwind v4 preset, inspired by [@maizzle/tailwindcss](https://github.com/maizzle/tailwindcss)
+
+```css
+/* styles.css */
+@import '@keycloakify/angular-email/tailwindcss-preset-email';
+```
 
-**NB**: tailwind v4 is not supported due to high level css generation and poor support in overriding default utilities
+```typescript
+// email.component.ts
+...
+import { Component, ViewEncapsulation } from '@angular/core';
+import { render, RenderToHtml } from '@keycloakify/angular-email';
+// or your custom css processor implementation
+import { cssProcessor } from '@keycloakify/angular-email/tailwindcss-preset-email/css-processor';
 
-[add support for disabling core plugins](https://github.com/tailwindlabs/tailwindcss/discussions/16132)
 
-[Cannot override tailwind utilities](https://github.com/tailwindlabs/tailwindcss/issues/16856)
+...
+@Component({
+  ...
+  styleUrls: ['styles.css'],
+  encapsulation: ViewEncapsulation.None,
+})
+export class EmailComponent {
+  ....
+}
+
+type EmailComponentProps = {};
+
+export const renderToHtml: RenderToHtml<EmailComponentProps> = (props) => {
+  return render({
+    component: EmailComponent,
+    selector: 'app-root',
+    props,
+    options: {
+      pretty: true,
+      cssProcessor,
+    },
+  });
+};
+```
 
 ## Contributing
 

package/bin/build.mjs

@@ -1,155 +1,2 @@
 #!/usr/bin/env node
-import { angularEsbuildPlugin } from '@keycloakify/angular-email/esbuild';
-import esbuild from 'esbuild';
-import { readdir, rm, writeFile } from 'node:fs/promises';
-import { basename, join, resolve } from 'node:path';
-import { cwd, exit } from 'node:process';
-import { pathToFileURL } from 'node:url';
-import { termost } from 'termost';
-import pkg from '../package.json' with { type: 'json' };
-async function bundle(entryPoints, cwd, outdir) {
-    // we have to use a bundler to preprocess templates code
-    // It's better to not use the same bundling configuration used for the
-    // frontend theme, because for email templates there might be a different
-    // transpiling settings, such as other jsx-pragma or additional transpilation plugins,
-    const result = await esbuild.build({
-        entryPoints: entryPoints,
-        bundle: true,
-        splitting: true,
-        outdir,
-        absWorkingDir: cwd,
-        platform: 'node',
-        sourcemap: true,
-        packages: 'bundle',
-        external: ['juice', 'postcss', 'tailwindcss-v3'],
-        format: 'esm',
-        outExtension: { '.js': '.mjs' },
-        target: 'node20',
-        plugins: [angularEsbuildPlugin(cwd)],
-        metafile: true,
-    });
-    // collect map of entrypoints -> output files
-    // esbuild return paths relative to the CWD
-    // https://github.com/evanw/esbuild/issues/338
-    return Object.entries(result.metafile.outputs).reduce((acc, [filePath, meta]) => {
-        if (meta.entryPoint) {
-            // Absolute pathes doesn't work on windows.
-            // Have to use `pathToFileURL` to convert it to url
-            acc[resolve(cwd, meta.entryPoint)] = pathToFileURL(resolve(cwd, filePath)).toString();
-        }
-        return acc;
-    }, {});
-}
-async function getTemplates(dirPath, filterTemplate) {
-    try {
-        const recursiveGetFiles = async (path) => {
-            const items = await readdir(path, { withFileTypes: true });
-            const dirents = [];
-            for (const item of items) {
-                if (item.isFile())
-                    dirents.push(item);
-                else if (item.isDirectory()) {
-                    dirents.push(...(await recursiveGetFiles(join(item.parentPath, item.name))));
-                }
-            }
-            return dirents;
-        };
-        // Read all items in the directory
-        const items = (await recursiveGetFiles(dirPath))
-            .map((file) => join(file.parentPath, file.name))
-            .filter((filePath) => {
-            if (!filterTemplate)
-                return true;
-            return filterTemplate(filePath);
-        });
-        return items;
-    }
-    catch (err) {
-        console.error(`Error scanning directory: ${err.message}`);
-        throw err;
-    }
-}
-const build = async (emailFilesPath, outdir = 'dist/emails') => {
-    if (!emailFilesPath) {
-        console.error('emailFilesPath is required!');
-        exit(1);
-    }
-    try {
-        console.log(`building emails to ${outdir}...`);
-        const tmp = join(cwd(), outdir, '.tmp');
-        await rm(outdir, { recursive: true, force: true });
-        const tpls = await getTemplates(resolve(cwd(), emailFilesPath), (path) => path.endsWith('.ts'));
-        if (!tpls.length) {
-            console.error('no templates found!');
-            exit(1);
-        }
-        const entryPoints = [...tpls];
-        const bundled = await bundle(entryPoints, cwd(), tmp);
-        const promises = tpls.map(async (file) => {
-            const module = await import(bundled[file]);
-            console.log(`- ${file}`);
-            return Object.assign(Object.assign({}, module), { file });
-        });
-        const modules = await Promise.all(promises);
-        for (const module of modules) {
-            const html = await module.renderToHtml();
-            await writeFile(`${outdir}/${basename(module.file).split('.')[0]}.html`, html);
-        }
-        await rm(tmp, { recursive: true, force: true });
-        console.log('\x1b[36m%s\x1b[0m', `build complete!`);
-        exit(0);
-    }
-    catch (error) {
-        console.error(error);
-        exit(1);
-    }
-};
-const program = termost({
-    name: 'keycloakify-angular-email',
-    description: 'Keycloakify CLI',
-    version: pkg.version,
-    onException: (error) => {
-        console.error(error);
-        exit(1);
-    },
-});
-program.option({
-    key: 'emailFilesPath',
-    name: { long: 'emailFilesPath', short: 'p' },
-    description: '',
-    defaultValue: '',
-});
-program.option({
-    key: 'outDir',
-    name: { long: 'outDir', short: 'o' },
-    description: '',
-    defaultValue: 'dist/emails',
-});
-program
-    .command({
-    name: 'build',
-    description: 'build angular components to html',
-})
-    .input({
-    key: 'emailFilesPath',
-    type: 'text',
-    defaultValue: undefined,
-    label: "what's the path of your email components files?",
-    skip(context) {
-        return Boolean(context.emailFilesPath);
-    },
-})
-    .input({
-    key: 'outDir',
-    type: 'text',
-    defaultValue: 'dist/emails',
-    label: 'where do you want to output html files?',
-    skip(context) {
-        return Boolean(context.outDir);
-    },
-})
-    .task({
-    handler: async (context) => {
-        await build(context.emailFilesPath, context.outDir);
-    },
-});
+import{angularEsbuildPlugin as b}from"@keycloakify/angular-email/esbuild";import k from"esbuild";import{readdir as w,rm as f,writeFile as P}from"node:fs/promises";import{basename as x,join as g,resolve as p}from"node:path";import{cwd as c,exit as m}from"node:process";import{pathToFileURL as F}from"node:url";import{termost as D}from"termost";import v from"../package.json"with{type:"json"};async function E(e,t,i,a=[]){const r=await k.build({entryPoints:e,bundle:!0,splitting:!0,outdir:i,absWorkingDir:t,platform:"node",sourcemap:!0,packages:"bundle",external:["juice",...a],format:"esm",outExtension:{".js":".mjs"},target:"node20",plugins:[b(t)],metafile:!0});return Object.entries(r.metafile.outputs).reduce((l,[s,o])=>(o.entryPoint&&(l[p(t,o.entryPoint)]=F(p(t,s)).toString()),l),{})}async function j(e,t){try{const i=async r=>{const l=await w(r,{withFileTypes:!0}),s=[];for(const o of l)o.isFile()?s.push(o):o.isDirectory()&&s.push(...await i(g(o.parentPath,o.name)));return s};return(await i(e)).map(r=>g(r.parentPath,r.name)).filter(r=>t?t(r):!0)}catch(i){throw console.error(`Error scanning directory: ${i.message}`),i}}const C=async(e,t="dist/emails",i=[])=>{e||(console.error("emailFilesPath is required!"),m(1));try{console.log(`building emails to ${t}...`);const a=g(c(),t,".tmp");await f(t,{recursive:!0,force:!0});const r=await j(p(c(),e),n=>n.endsWith(".ts"));r.length||(console.error("no templates found!"),m(1));const l=[...r],s=await E(l,c(),a,i),o=r.map(async n=>{const u=s[n]??s[p(c(),n)];if(!u)throw new Error(`Failed to locate bundled URL for "${n}". Ensure getTemplates() returns absolute paths and esbuild.metafile entryPoint mapping uses the same base.`);const h=await import(u);return console.log(`- ${n}`),{...h,file:n}}),y=await Promise.all(o);for(const n of y){const u=await n.renderToHtml();await P(`${t}/${x(n.file).split(".")[0]}.html`,u)}await f(a,{recursive:!0,force:!0}),console.log("\x1B[36m%s\x1B[0m","build complete!"),m(0)}catch(a){console.error(a),m(1)}},d=D({name:"keycloakify-angular-email",description:"Keycloakify CLI",version:v.version,onException:e=>{console.error(e),m(1)}});d.option({key:"emailFilesPath",name:{long:"emailFilesPath",short:"p"},description:"input directory for angular email components",defaultValue:""}),d.option({key:"outDir",name:{long:"outDir",short:"o"},description:"output directory for generated html",defaultValue:"dist/emails"}),d.option({key:"externals",name:{long:"externals",short:"e"},description:"Comma-separated packages to mark as external in esbuild (e.g. tailwindcss,postcss,postcss-calc)",defaultValue:""}),d.command({name:"build",description:"build angular components to html"}).input({key:"emailFilesPath",type:"text",defaultValue:void 0,label:"what's the path of your email components files?",skip(e){return!!e.emailFilesPath}}).input({key:"outDir",type:"text",defaultValue:"dist/emails",label:"where do you want to output html files?",skip(e){return!!e.outDir}}).input({key:"externals",type:"text",label:"any additional package to mark as external (comma separated)?",skip(){return!0}}).task({handler:async e=>{let t=[];e.externals&&(t=e.externals.split(",").map(i=>i.trim()).filter(Boolean)),await C(e.emailFilesPath,e.outDir,t)}});

package/fesm2022/keycloakify-angular-email-tailwindcss-preset-email-css-processor.mjs

@@ -0,0 +1,70 @@
+import tailwindcss from '@tailwindcss/postcss';
+import postcss from 'postcss';
+import calc from 'postcss-calc';
+import properties from 'postcss-custom-properties';
+import logical from 'postcss-logical';
+import preset from 'postcss-preset-env';
+
+const cssProcessor = async (style) => {
+    try {
+        const result = await postcss(tailwindcss(), properties({ preserve: false }), calc({ preserve: false }), {
+            postcssPlugin: 'inline-tw-vars-from-layer',
+            Once(root) {
+                const defaultVars = new Map();
+                // 1. Find the default variables in @layer properties
+                root.walkAtRules('layer', (layerRule) => {
+                    if (layerRule.params === 'properties') {
+                        layerRule.walkDecls(/^--tw-/, (decl) => {
+                            defaultVars.set(decl.prop, decl.value);
+                        });
+                    }
+                });
+                // 2. Walk all rules and replace var() usages
+                root.walkDecls((decl) => {
+                    decl.value = decl.value.replace(/var\((--tw-[^,)]+)\)/g, (match, varName) => {
+                        return defaultVars.has(varName) ? defaultVars.get(varName) : match;
+                    });
+                });
+            },
+        }, {
+            postcssPlugin: 'remove-unused-tw-vars',
+            Once(root) {
+                root.walkDecls(/^--tw-/, (decl) => {
+                    decl.remove();
+                });
+                root.walkAtRules('property', (atRule) => {
+                    if (atRule.params.startsWith('--tw-')) {
+                        atRule.remove();
+                    }
+                });
+                root.walkAtRules('layer', (atRule) => {
+                    if (atRule.params === 'properties') {
+                        atRule.remove();
+                    }
+                });
+            },
+        }, logical({
+            blockDirection: 'top-to-bottom',
+            inlineDirection: 'left-to-right',
+        }), preset({
+            stage: 4,
+            minimumVendorImplementations: 3,
+            logical: {
+                blockDirection: 'top-to-bottom',
+                inlineDirection: 'left-to-right',
+            },
+        })).process(style, { map: false, from: undefined });
+        return result.css;
+    }
+    catch (error) {
+        console.error('CSS processing failed:', error);
+        throw new Error(`Failed to process CSS: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+};
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { cssProcessor };
+//# sourceMappingURL=keycloakify-angular-email-tailwindcss-preset-email-css-processor.mjs.map

package/fesm2022/keycloakify-angular-email-tailwindcss-preset-email-css-processor.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"keycloakify-angular-email-tailwindcss-preset-email-css-processor.mjs","sources":["../../../projects/angular-email/tailwindcss-preset-email/css-processor/css-processor.ts","../../../projects/angular-email/tailwindcss-preset-email/css-processor/keycloakify-angular-email-tailwindcss-preset-email-css-processor.ts"],"sourcesContent":["import tailwindcss from '@tailwindcss/postcss';\nimport postcss from 'postcss';\nimport calc from 'postcss-calc';\nimport properties from 'postcss-custom-properties';\nimport logical, { type DirectionFlow } from 'postcss-logical';\nimport preset from 'postcss-preset-env';\n\nexport const cssProcessor = async (style: string) => {\n  try {\n    const result = await postcss(\n      tailwindcss(),\n      properties({ preserve: false }),\n      calc({ preserve: false }),\n      {\n        postcssPlugin: 'inline-tw-vars-from-layer',\n        Once(root) {\n          const defaultVars = new Map<string, string>();\n\n          // 1. Find the default variables in @layer properties\n          root.walkAtRules('layer', (layerRule) => {\n            if (layerRule.params === 'properties') {\n              layerRule.walkDecls(/^--tw-/, (decl) => {\n                defaultVars.set(decl.prop, decl.value);\n              });\n            }\n          });\n\n          // 2. Walk all rules and replace var() usages\n          root.walkDecls((decl) => {\n            decl.value = decl.value.replace(/var\\((--tw-[^,)]+)\\)/g, (match, varName) => {\n              return defaultVars.has(varName) ? defaultVars.get(varName)! : match;\n            });\n          });\n        },\n      },\n      {\n        postcssPlugin: 'remove-unused-tw-vars',\n        Once(root) {\n          root.walkDecls(/^--tw-/, (decl) => {\n            decl.remove();\n          });\n          root.walkAtRules('property', (atRule) => {\n            if (atRule.params.startsWith('--tw-')) {\n              atRule.remove();\n            }\n          });\n          root.walkAtRules('layer', (atRule) => {\n            if (atRule.params === 'properties') {\n              atRule.remove();\n            }\n          });\n        },\n      },\n      logical({\n        blockDirection: 'top-to-bottom' as DirectionFlow,\n        inlineDirection: 'left-to-right' as DirectionFlow,\n      }),\n      preset({\n        stage: 4,\n        minimumVendorImplementations: 3,\n        logical: {\n          blockDirection: 'top-to-bottom' as DirectionFlow,\n          inlineDirection: 'left-to-right' as DirectionFlow,\n        },\n      }),\n    ).process(style, { map: false, from: undefined });\n    return result.css;\n  } catch (error) {\n    console.error('CSS processing failed:', error);\n    throw new Error(`Failed to process CSS: ${error instanceof Error ? error.message : 'Unknown error'}`);\n  }\n};\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":";;;;;;;MAOa,YAAY,GAAG,OAAO,KAAa,KAAI;AAClD,IAAA,IAAI;QACF,MAAM,MAAM,GAAG,MAAM,OAAO,CAC1B,WAAW,EAAE,EACb,UAAU,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,EAC/B,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,EACzB;AACE,YAAA,aAAa,EAAE,2BAA2B;AAC1C,YAAA,IAAI,CAAC,IAAI,EAAA;AACP,gBAAA,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB;;gBAG7C,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,SAAS,KAAI;AACtC,oBAAA,IAAI,SAAS,CAAC,MAAM,KAAK,YAAY,EAAE;wBACrC,SAAS,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,IAAI,KAAI;4BACrC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC;AACxC,yBAAC,CAAC;;AAEN,iBAAC,CAAC;;AAGF,gBAAA,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,KAAI;AACtB,oBAAA,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,uBAAuB,EAAE,CAAC,KAAK,EAAE,OAAO,KAAI;AAC1E,wBAAA,OAAO,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,OAAO,CAAE,GAAG,KAAK;AACrE,qBAAC,CAAC;AACJ,iBAAC,CAAC;aACH;SACF,EACD;AACE,YAAA,aAAa,EAAE,uBAAuB;AACtC,YAAA,IAAI,CAAC,IAAI,EAAA;gBACP,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,IAAI,KAAI;oBAChC,IAAI,CAAC,MAAM,EAAE;AACf,iBAAC,CAAC;gBACF,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC,MAAM,KAAI;oBACtC,IAAI,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE;wBACrC,MAAM,CAAC,MAAM,EAAE;;AAEnB,iBAAC,CAAC;gBACF,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,MAAM,KAAI;AACnC,oBAAA,IAAI,MAAM,CAAC,MAAM,KAAK,YAAY,EAAE;wBAClC,MAAM,CAAC,MAAM,EAAE;;AAEnB,iBAAC,CAAC;aACH;AACF,SAAA,EACD,OAAO,CAAC;AACN,YAAA,cAAc,EAAE,eAAgC;AAChD,YAAA,eAAe,EAAE,eAAgC;SAClD,CAAC,EACF,MAAM,CAAC;AACL,YAAA,KAAK,EAAE,CAAC;AACR,YAAA,4BAA4B,EAAE,CAAC;AAC/B,YAAA,OAAO,EAAE;AACP,gBAAA,cAAc,EAAE,eAAgC;AAChD,gBAAA,eAAe,EAAE,eAAgC;AAClD,aAAA;AACF,SAAA,CAAC,CACH,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACjD,OAAO,MAAM,CAAC,GAAG;;IACjB,OAAO,KAAK,EAAE;AACd,QAAA,OAAO,CAAC,KAAK,CAAC,wBAAwB,EAAE,KAAK,CAAC;AAC9C,QAAA,MAAM,IAAI,KAAK,CAAC,0BAA0B,KAAK,YAAY,KAAK,GAAG,KAAK,CAAC,OAAO,GAAG,eAAe,CAAA,CAAE,CAAC;;AAEzG;;ACvEA;;AAEG;;;;"}