@keycloakify/angular-email 0.0.1-rc.2 → 0.0.1-rc.20

package/README.md

@@ -1,6 +1,6 @@
 # Angular Email
 
-Angular Email is a library that enables email template development using Angular, inspired by [jsx-email](https://github.com/rezqio/jsx-email). It provides a way to create email components using Angular's templating system.
+Angular Email is a library that enables email template development using Angular, inspired by [jsx-email](https://github.com/shellscape/jsx-email). It provides a way to create email components using Angular's templating system.
 
 ## Installation
 
@@ -23,22 +23,69 @@ see this [example](https://github.com/keycloakify/angular-email/blob/main/projec
 To render the email as HTML or plaintext, use Angular's rendering engine:
 
 ```typescript
+// email.component.ts
 ...
-import { render } from '@keycloakify/angular-email';
+import { render, RenderToHtml } from '@keycloakify/angular-email';
 
-const emailHtml = render({
-  component: AppComponent,
-  selector: 'app-root',
-  options: {
-    pretty: true,
-  },
-}).then((emailHtml) => {
-  console.log(emailHtml);
-});
+...
+export class EmailComponent {
+  ....
+}
+
+type EmailComponentProps = {};
+
+export const renderToHtml: RenderToHtml<EmailComponentProps> = (props) => {
+  return render({
+    component: EmailComponent,
+    selector: 'app-root',
+    props,
+    options: {
+      pretty: true,
+    },
+  });
+};
 ```
 
+```sh
+# cmd
+
+export $EMAIL_COMPONENTS_DIR_PATH="src/emails"
+npx keycloakify-angular-email build -p $EMAIL_COMPONENTS_DIR_PATH
+```
+
+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
 
+```ts
+// email.component.ts
+...
+import { render } from '@keycloakify/angular-email';
+import type { GetSubject, GetTemplate } from 'keycloakify-emails';
+
+...
+export class EmailComponent {
+  ....
+}
+
+export const getTemplate: GetTemplate = async (props) => {
+  return await render({
+    component: EmailComponent,
+    props,
+    selector: 'kc-email-test',
+    options: {
+      signalInputsPrefix: '$',
+      pretty: true,
+      plainText: props.plainText,
+    },
+  });
+};
+
+export const getSubject: GetSubject = async (_props) => {
+  return '[KEYCLOAK] - SMTP test message';
+};
+```
+
 ```ts
 // vite.config.ts
 
@@ -55,14 +102,16 @@ export default defineConfig(({ mode }) => ({
       postBuild: async (buildContext) => {
         await buildEmailTheme({
           templatesSrcDirPath: join(import.meta.dirname, '/emails/templates'),
-          filterTemplate: (filePath: string) => !filePath.endsWith('.html'),
+          filterTemplate: (filePath: string) => !!filePath.endsWith('.component.ts'),
           themeNames: buildContext.themeNames,
           keycloakifyBuildDirPath: buildContext.keycloakifyBuildDirPath,
           locales: ['en'],
           cwd: import.meta.dirname,
           esbuild: {
             packages: 'bundle',
-            external: ['cheerio'],
+            external: ['juice', 'postcss'],
+            format: 'cjs',
+            outExtension: { '.js': '.cjs' },
             plugins: [angularEsbuildPlugin(import.meta.dirname)],
           },
         });
@@ -72,6 +121,104 @@ export default defineConfig(({ mode }) => ({
 }));
 ```
 
+### Standalone Dynamic Rendering
+
+Use it in a server environment
+
+```js
+// index.mjs
+
+import { toHTML } from '@keycloakify/angular-email/node';
+
+toHTML({
+  filePath: 'path/to/your.component.ts',
+  props: { foo: 'bar' },
+})
+  .then((html) => {
+    console.log(html);
+  })
+  .catch((e) => {
+    console.error(e);
+  });
+```
+
+or
+
+```js
+// index.cjs
+
+const { toHTML } = require('@keycloakify/angular-email/node');
+
+toHTML({
+  filePath: 'path/to/your.component.ts',
+  props: { foo: 'bar' },
+})
+  .then((html) => {
+    console.log(html);
+  })
+  .catch((e) => {
+    console.error(e);
+  });
+```
+
+```sh
+# cmd
+
+node index.mjs # or node index.cjs
+```
+
+## API
+
+### @keycloakify/angular-email
+
+### Render
+
+```ts
+type Render<Input extends Record<string, any>> = {
+  component: Type<unknown>;
+  /** Component selector */
+  selector: string;
+  /** Component inputs */
+  props?: Input;
+  options?: {
+    /** render as text */
+    plainText?: boolean;
+    /** format the html output */
+    pretty?: boolean;
+    /** tailwind configuration object */
+    tailwindConfig?: Partial<Config>;
+    /** if you use prefix conventions on signal inputs */
+    signalInputsPrefix?: string;
+  };
+};
+```
+
+### render()
+
+```ts
+render<Input extends Record<string, any>>({ component, selector, props, options }: Render<Input>) => Promise<string>
+```
+
+### @keycloakify/angular-email/esbuild
+
+### angularEsbuildPlugin()
+
+```ts
+angularEsbuildPlugin(cwd: string) => Plugin
+```
+
+### @keycloakify/angular-email/node
+
+### toHTML()
+
+```ts
+toHTML<Input extends Record<string, any>>(options: {
+    filePath: string;
+    props?: Input;
+    root?: string;
+}) => Promise<string>
+```
+
 ## Contributing
 
 Contributions are welcome! Feel free to open an issue or submit a pull request on [GitHub](https://github.com/keycloakify/angular-email).

package/bin/build.mjs

@@ -0,0 +1,154 @@
+#!/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,
+        outdir,
+        absWorkingDir: cwd,
+        platform: 'node',
+        sourcemap: true,
+        packages: 'bundle',
+        external: ['juice', 'postcss'],
+        format: 'cjs',
+        outExtension: { '.js': '.cjs' },
+        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);
+        modules.forEach(async (module) => {
+            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);
+    },
+});

package/esbuild/esbuild.d.ts

@@ -1 +1,2 @@
-export declare const angularEsbuildPlugin: (cwd: string) => import("esbuild").Plugin;
+import { Plugin } from 'esbuild';
+export declare const angularEsbuildPlugin: (cwd: string) => Plugin;

package/fesm2022/keycloakify-angular-email-esbuild.mjs

@@ -13,10 +13,10 @@ const angularEsbuildPlugin = (cwd) => createCompilerPlugin({
     },
     inlineFonts: false,
     inlineStyleLanguage: 'css',
-    optimization: false,
+    optimization: true,
     sourcemap: false,
     target: [],
-    workspaceRoot: '',
+    workspaceRoot: cwd,
     outputNames: { bundles: '', media: '' },
 });
 

package/fesm2022/keycloakify-angular-email-esbuild.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"keycloakify-angular-email-esbuild.mjs","sources":["../../../projects/angular-email/esbuild/esbuild.ts","../../../projects/angular-email/esbuild/keycloakify-angular-email-esbuild.ts"],"sourcesContent":["import { createCompilerPlugin } from '@angular/build/private';\n\nexport const angularEsbuildPlugin = (cwd: string) =>\n  createCompilerPlugin(\n    {\n      browserOnlyBuild: false,\n      incremental: false,\n      sourcemap: true,\n      tsconfig: cwd + '/tsconfig.json',\n    },\n    {\n      cacheOptions: {\n        basePath: cwd + '/.angular/cache',\n        enabled: false,\n        path: cwd + '/.angular/cache/angular-email',\n      },\n      inlineFonts: false,\n      inlineStyleLanguage: 'css',\n      optimization: false,\n      sourcemap: false,\n      target: [],\n      workspaceRoot: '',\n      outputNames: { bundles: '', media: '' },\n    },\n  );\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":";;AAEa,MAAA,oBAAoB,GAAG,CAAC,GAAW,KAC9C,oBAAoB,CAClB;AACE,IAAA,gBAAgB,EAAE,KAAK;AACvB,IAAA,WAAW,EAAE,KAAK;AAClB,IAAA,SAAS,EAAE,IAAI;IACf,QAAQ,EAAE,GAAG,GAAG,gBAAgB;CACjC,EACD;AACE,IAAA,YAAY,EAAE;QACZ,QAAQ,EAAE,GAAG,GAAG,iBAAiB;AACjC,QAAA,OAAO,EAAE,KAAK;QACd,IAAI,EAAE,GAAG,GAAG,+BAA+B;AAC5C,KAAA;AACD,IAAA,WAAW,EAAE,KAAK;AAClB,IAAA,mBAAmB,EAAE,KAAK;AAC1B,IAAA,YAAY,EAAE,KAAK;AACnB,IAAA,SAAS,EAAE,KAAK;AAChB,IAAA,MAAM,EAAE,EAAE;AACV,IAAA,aAAa,EAAE,EAAE;IACjB,WAAW,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;AACxC,CAAA;;ACvBL;;AAEG;;;;"}
+{"version":3,"file":"keycloakify-angular-email-esbuild.mjs","sources":["../../../projects/angular-email/esbuild/esbuild.ts","../../../projects/angular-email/esbuild/keycloakify-angular-email-esbuild.ts"],"sourcesContent":["import { createCompilerPlugin } from '@angular/build/private';\nimport { Plugin } from 'esbuild';\n\nexport const angularEsbuildPlugin = (cwd: string): Plugin =>\n  createCompilerPlugin(\n    {\n      browserOnlyBuild: false,\n      incremental: false,\n      sourcemap: true,\n      tsconfig: cwd + '/tsconfig.json',\n    },\n    {\n      cacheOptions: {\n        basePath: cwd + '/.angular/cache',\n        enabled: false,\n        path: cwd + '/.angular/cache/angular-email',\n      },\n      inlineFonts: false,\n      inlineStyleLanguage: 'css',\n      optimization: true,\n      sourcemap: false,\n      target: [],\n      workspaceRoot: cwd,\n      outputNames: { bundles: '', media: '' },\n    },\n  );\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":";;AAGa,MAAA,oBAAoB,GAAG,CAAC,GAAW,KAC9C,oBAAoB,CAClB;AACE,IAAA,gBAAgB,EAAE,KAAK;AACvB,IAAA,WAAW,EAAE,KAAK;AAClB,IAAA,SAAS,EAAE,IAAI;IACf,QAAQ,EAAE,GAAG,GAAG,gBAAgB;CACjC,EACD;AACE,IAAA,YAAY,EAAE;QACZ,QAAQ,EAAE,GAAG,GAAG,iBAAiB;AACjC,QAAA,OAAO,EAAE,KAAK;QACd,IAAI,EAAE,GAAG,GAAG,+BAA+B;AAC5C,KAAA;AACD,IAAA,WAAW,EAAE,KAAK;AAClB,IAAA,mBAAmB,EAAE,KAAK;AAC1B,IAAA,YAAY,EAAE,IAAI;AAClB,IAAA,SAAS,EAAE,KAAK;AAChB,IAAA,MAAM,EAAE,EAAE;AACV,IAAA,aAAa,EAAE,GAAG;IAClB,WAAW,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;AACxC,CAAA;;ACxBL;;AAEG;;;;"}