@maizzle/framework 5.0.0-beta.11 → 5.0.0-beta.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maizzle/framework",
-  "version": "5.0.0-beta.11",
+  "version": "5.0.0-beta.13",
   "description": "Maizzle is a framework that helps you quickly build HTML emails with Tailwind CSS.",
   "license": "MIT",
   "type": "module",

package/src/generators/render.js

@@ -4,8 +4,9 @@ import { cwd } from 'node:process'
 import { defu as merge } from 'defu'
 import expressions from 'posthtml-expressions'
 import { parseFrontMatter } from '../utils/node.js'
+import defaultConfig from '../posthtml/defaultConfig.js'
 import { process as compilePostHTML } from '../posthtml/index.js'
-import { run as useTransformers, transformers } from '../transformers/index.js'
+import { run as useTransformers } from '../transformers/index.js'
 
 export async function render(html = '', config = {}) {
   if (typeof html !== 'string') {
@@ -40,7 +41,7 @@ export async function render(html = '', config = {}) {
       })
     ]
   )
-    .process(matter)
+    .process(matter, defaultConfig)
     .then(({ html }) => parseFrontMatter(`---${html}\n---`))
 
   const templateConfig = merge(matterData, config)
@@ -57,16 +58,18 @@ export async function render(html = '', config = {}) {
    *
    * @param {Object} options
    * @param {string} options.html - The HTML to be transformed
+   * @param {Object} options.matter - The front matter data
    * @param {Object} options.config - The current template config
-   * @param {function} options.render - The render function
+   * @param {function} options.posthtml - The PostHTML compiler
+   * @param {Object} options.transform - The transformers object
    * @returns {string} - The transformed HTML, or the original one if nothing was returned
    */
   if (typeof templateConfig.beforeRender === 'function') {
     content = await templateConfig.beforeRender(({
       html: content,
+      matter: matterData,
       config: templateConfig,
       posthtml: compilePostHTML,
-      transform: transformers,
     })) ?? content
   }
 
@@ -78,16 +81,18 @@ export async function render(html = '', config = {}) {
    *
    * @param {Object} options
    * @param {string} options.html - The HTML to be transformed
+   * @param {Object} options.matter - The front matter data
    * @param {Object} options.config - The current template config
-   * @param {function} options.render - The render function
+   * @param {function} options.posthtml - The PostHTML compiler
+   * @param {Object} options.transform - The transformers object
    * @returns {string} - The transformed HTML, or the original one if nothing was returned
    */
   if (typeof templateConfig.afterRender === 'function') {
     compiled.html = await templateConfig.afterRender(({
       html: compiled.html,
+      matter: matterData,
       config: templateConfig,
       posthtml: compilePostHTML,
-      transform: transformers,
     })) ?? compiled.html
   }
 
@@ -111,16 +116,18 @@ export async function render(html = '', config = {}) {
    *
    * @param {Object} options
    * @param {string} options.html - The HTML to be transformed
+   * @param {Object} options.matter - The front matter data
    * @param {Object} options.config - The current template config
-   * @param {function} options.render - The render function
+   * @param {function} options.posthtml - The PostHTML compiler
+   * @param {Object} options.transform - The transformers object
    * @returns {string} - The transformed HTML, or the original one if nothing was returned
    */
   if (typeof templateConfig.afterTransformers === 'function') {
     compiled.html = await templateConfig.afterTransformers(({
       html: compiled.html,
+      matter: matterData,
       config: templateConfig,
       posthtml: compilePostHTML,
-      transform: transformers,
     })) ?? compiled.html
   }
 

package/src/transformers/addAttributes.js

@@ -11,7 +11,7 @@ export default function posthtmlPlugin(attributes = {}) {
       role: 'none'
     },
     img: {
-      alt: ''
+      alt: true,
     }
   }
 

package/src/transformers/comb.js

@@ -37,7 +37,7 @@ const posthtmlPlugin = options => tree => {
 
   const { result: html } = emailComb(render(tree), options)
 
-  return parse(html)
+  return parse(html, posthtmlConfig)
 }
 
 export default posthtmlPlugin

package/src/transformers/index.js

@@ -2,6 +2,7 @@ import posthtml from 'posthtml'
 import get from 'lodash-es/get.js'
 import { defu as merge } from 'defu'
 
+import core from './core.js'
 import comb from './comb.js'
 import sixHex from './sixHex.js'
 import minify from './minify.js'
@@ -21,19 +22,17 @@ import replaceStrings from './replaceStrings.js'
 import attributeToStyle from './attributeToStyle.js'
 import removeAttributes from './removeAttributes.js'
 
-import coreTransformers from './core.js'
-
 import defaultPosthtmlConfig from '../posthtml/defaultConfig.js'
 
 /**
  * Use Maizzle Transformers on an HTML string.
  *
- * Only Transformers that are enabled in the `config` will be used.
+ * Only Transformers that are enabled in the passed
+ * `config` parameter will be used.
  *
  * @param {string} html The HTML content
  * @param {object} config The Maizzle config object
- * @returns {Promise<{ original: string, config: object, html: string }>}
- *   A Promise resolving to an object containing the original HTML, modified HTML, and the config
+ * @returns {Promise<{ html: string }>} A Promise resolving to an object containing the modified HTML
  */
 export async function run(html = '', config = {}) {
   const posthtmlPlugins = []
@@ -46,16 +45,16 @@ export async function run(html = '', config = {}) {
   /**
    * 1. Core transformers
    *
-   * Transformers that are always enabled
+   * Transformers that are always enabled.
    *
    */
-  posthtmlPlugins.push(coreTransformers(config))
+  posthtmlPlugins.push(core(config))
 
   /**
    * 2. Safe class names
    *
    * Rewrite Tailwind CSS class names to email-safe alternatives,
-   * unless explicitly disabled
+   * unless explicitly disabled.
    */
   if (get(config, 'css.safe') !== false) {
     posthtmlPlugins.push(
@@ -66,7 +65,6 @@ export async function run(html = '', config = {}) {
   /**
    * 3. Filters
    *
-   * Apply filters to HTML.
    * Filters are always applied, unless explicitly disabled.
    */
   if (get(config, 'filters') !== false) {
@@ -78,7 +76,7 @@ export async function run(html = '', config = {}) {
   /**
    * 4. Markdown
    *
-   * Convert Markdown to HTML with Markdown-it, unless explicitly disabled
+   * Convert Markdown to HTML with markdown-it, unless explicitly disabled.
    */
   if (get(config, 'markdown') !== false) {
     posthtmlPlugins.push(
@@ -88,7 +86,9 @@ export async function run(html = '', config = {}) {
 
   /**
    * 5. Prevent widow words
-   * Always runs, unless explicitly disabled
+   *
+   * Enabled by default, will prevent widow words in elements
+   * wrapped with a `prevent-widows` attribute.
    */
   if (get(config, 'widowWords') !== false) {
     posthtmlPlugins.push(
@@ -110,7 +110,7 @@ export async function run(html = '', config = {}) {
   /**
    * 7. Inline CSS
    *
-   * Inline CSS into HTML
+   * Inline CSS into HTML.
    */
   if (get(config, 'css.inline')) {
     posthtmlPlugins.push(inlineCSS(
@@ -150,7 +150,7 @@ export async function run(html = '', config = {}) {
   /**
    * 10. Shorthand CSS
    *
-   * Convert longhand CSS properties to shorthand in `style` attributes
+   * Convert longhand CSS properties to shorthand in `style` attributes.
    */
   if (get(config, 'css.shorthand')) {
     posthtmlPlugins.push(
@@ -161,7 +161,7 @@ export async function run(html = '', config = {}) {
   /**
    * 11. Add attributes
    *
-   * Add attributes to HTML tags
+   * Add attributes to HTML tags.
    */
   if (get(config, 'attributes.add') !== false) {
     posthtmlPlugins.push(
@@ -172,7 +172,7 @@ export async function run(html = '', config = {}) {
   /**
    * 12. Base URL
    *
-   * Add a base URL to relative paths
+   * Add a base URL to relative paths.
    */
   if (get(config, 'baseURL', get(config, 'baseUrl'))) {
     posthtmlPlugins.push(
@@ -180,7 +180,7 @@ export async function run(html = '', config = {}) {
     )
   } else {
     /**
-     * Set baseURL to `build.static.destination` if it's not already set
+     * Set baseURL to `build.static.destination` if it's not already set.
      */
     const destination = get(config, 'build.static.destination', '')
     if (destination && !config._dev) {
@@ -198,7 +198,7 @@ export async function run(html = '', config = {}) {
   /**
    * 13. URL parameters
    *
-   * Add parameters to URLs
+   * Add parameters to URLs.
    */
   if (get(config, 'urlParameters')) {
     posthtmlPlugins.push(
@@ -209,8 +209,7 @@ export async function run(html = '', config = {}) {
   /**
    * 14. Six-digit HEX
    *
-   * Convert three-digit HEX colors to six-digit
-   * Always runs, unless explicitly disabled
+   * Enabled by default, converts three-digit HEX colors to six-digit.
    */
   if (get(config, 'css.sixHex') !== false) {
     posthtmlPlugins.push(
@@ -221,7 +220,7 @@ export async function run(html = '', config = {}) {
   /**
    * 15. PostHTML MSO
    *
-   * Simplify writing MSO conditionals for Outlook
+   * Enabled by default, simplifies writing MSO conditionals for Outlook.
    */
   if (get(config, 'outlook') !== false) {
     posthtmlPlugins.push(
@@ -232,7 +231,7 @@ export async function run(html = '', config = {}) {
   /**
    * 16. Prettify
    *
-   * Pretty-print HTML using js-beautify
+   * Pretty-print HTML using js-beautify.
    */
   if (get(config, 'prettify')) {
     posthtmlPlugins.push(
@@ -243,7 +242,7 @@ export async function run(html = '', config = {}) {
   /**
    * 17. Minify
    *
-   * Minify HTML using html-crush
+   * Minify HTML using html-crush.
    */
   if (get(config, 'minify')) {
     posthtmlPlugins.push(
@@ -254,14 +253,14 @@ export async function run(html = '', config = {}) {
   /**
    * 18. <template> tags
    *
-   * Replace <template> tags with their content
+   * Replace <template> tags with their content.
    */
   posthtmlPlugins.push(templateTag())
 
   /**
    * 19. Replace strings
    *
-   * Replace strings through regular expressions
+   * Replace strings through regular expressions.
    */
   if (get(config, 'replaceStrings')) {
     posthtmlPlugins.push(
@@ -275,23 +274,3 @@ export async function run(html = '', config = {}) {
       html: result.html,
     }))
 }
-
-export const transformers = {
-  comb,
-  sixHex,
-  minify,
-  baseUrl,
-  inlineCSS,
-  prettify,
-  filters,
-  markdown,
-  posthtmlMso,
-  shorthandCss,
-  preventWidows,
-  addAttributes,
-  urlParameters,
-  safeClassNames,
-  replaceStrings,
-  attributeToStyle,
-  removeAttributes,
-}

package/src/transformers/inline.js

@@ -12,9 +12,10 @@ import isObject from 'lodash-es/isObject.js'
 import { parser as parse } from 'posthtml-parser'
 import { parseCSSRule } from '../utils/string.js'
 import { useAttributeSizes } from './useAttributeSizes.js'
+import defaultPostHTMLConfig from '../posthtml/defaultConfig.js'
 
 const posthtmlPlugin = (options = {}) => tree => {
-  return inline(render(tree), options).then(html => parse(html))
+  return inline(render(tree), options).then(html => parse(html, defaultPostHTMLConfig))
 }
 
 export default posthtmlPlugin

package/src/transformers/minify.js

@@ -4,6 +4,7 @@ import { defu as merge } from 'defu'
 import { render } from 'posthtml-render'
 import { parser as parse } from 'posthtml-parser'
 import posthtmlConfig from '../posthtml/defaultConfig.js'
+import defaultPostHTMLConfig from '../posthtml/defaultConfig.js'
 
 const posthtmlPlugin = (options = {}) => tree => {
   options = merge(options, {
@@ -12,7 +13,7 @@ const posthtmlPlugin = (options = {}) => tree => {
 
   const { result: html } = crush(render(tree), options)
 
-  return parse(html)
+  return parse(html, defaultPostHTMLConfig)
 }
 
 export default posthtmlPlugin

package/src/transformers/replaceStrings.js

@@ -4,6 +4,7 @@ import { render } from 'posthtml-render'
 import isEmpty from 'lodash-es/isEmpty.js'
 import { parser as parse } from 'posthtml-parser'
 import posthtmlConfig from '../posthtml/defaultConfig.js'
+import defaultPostHTMLConfig from '../posthtml/defaultConfig.js'
 
 const posthtmlPlugin = (replacements = {}) => tree => {
   if (!isEmpty(replacements)) {
@@ -17,7 +18,8 @@ const posthtmlPlugin = (replacements = {}) => tree => {
             return replacement
           }
         }
-      })
+      }),
+      defaultPostHTMLConfig
     )
   }
 

package/types/build.d.ts

@@ -1,13 +1,7 @@
-import ComponentsConfig from './components';
 import type { SpinnerName } from 'cli-spinners';
 import type ExpressionsConfig from './expressions';
 
 export default interface BuildConfig {
-  /**
-   * Components configuration.
-   */
-  components?: ComponentsConfig;
-
   /**
    * Paths where Maizzle should look for Templates to compile.
    *
@@ -22,7 +16,7 @@ export default interface BuildConfig {
    * }
    * ```
    */
-  content?: string | string[];
+  content?: string[];
 
   /**
   Configure expressions.
@@ -88,21 +82,6 @@ export default interface BuildConfig {
      * @default undefined
      */
     destination?: string;
-  } | {
-    /**
-     * An array of objects specifying source and destination directories for static files.
-     */
-    static: Array<{
-      /**
-       * Array of paths where Maizzle should look for static files.
-       */
-      source: string[];
-      /**
-       * Directory where static files should be copied to,
-       * relative to the `build.output` path.
-       */
-      destination: string;
-    }>;
   };
 
   /**

package/types/config.d.ts

@@ -1,9 +1,11 @@
+import type Events from './events';
 import type BuildConfig from './build';
 import type MinifyConfig from './minify';
 import type PostHTMLConfig from './posthtml';
 import type MarkdownConfig from './markdown';
 import type { ProcessOptions } from 'postcss';
 import type PurgeCSSConfig from './css/purge';
+import type PlaintextConfig from './plaintext';
 import type CSSInlineConfig from './css/inline';
 import type { SpinnerName } from 'cli-spinners';
 import type ComponentsConfig from './components';
@@ -11,20 +13,10 @@ import type WidowWordsConfig from './widowWords';
 import type { CoreBeautifyOptions } from 'js-beautify';
 import type { BaseURLConfig } from 'posthtml-base-url';
 import type URLParametersConfig from './urlParameters';
-import type {
-  beforeCreateType,
-  beforeRenderType,
-  afterRenderType,
-  afterTransformersType,
-  afterBuildType
-} from './events';
-import type PlaintextConfig from './plaintext';
 
 import type { Config as TailwindConfig } from 'tailwindcss';
 
 export default interface Config {
-  [key: string]: any; // eslint-disable-line
-
   /**
    * Add or remove attributes from elements.
    */
@@ -68,20 +60,8 @@ export default interface Config {
   }
 
   /**
-  Configure build settings.
-
-  @example
-  ```
-  export default {
-    build: {
-      components: ComponentsConfig,
-      posthtml: PostHTMLConfig,
-      tailwind: TailwindConfig,
-      templates: TemplatesConfig,
-    }
-  }
-  ```
-  */
+   * Configure build settings.
+   */
   build: BuildConfig;
 
   /**
@@ -185,7 +165,6 @@ export default interface Config {
 
     /**
      * Use a custom Tailwind CSS configuration object.
-     *
      */
     tailwind?: TailwindConfig;
   }
@@ -229,7 +208,7 @@ export default interface Config {
    * <p>{{ company.name }}</p>
    * ```
    */
-  locals?: Record<string, any>; // eslint-disable-line
+  locals?: Record<string, any>;
 
   /**
    * Configure the Markdown parser.
@@ -488,83 +467,87 @@ export default interface Config {
   * @example
   * ```
   * export default {
-  *   beforeCreate: async (config) => {
+  *   beforeCreate: async ({config}) => {
   *     // do something with `config`
   *   }
   * }
   * ```
   */
-  beforeCreate: beforeCreateType;
+  beforeCreate: Events['beforeCreate'];
 
   /**
    * Runs after the Template's config has been computed, but just before it is compiled.
-   * It exposes the Template's HTML, its config, and the Maizzle `render` function.
-   * Must return the `html` string.
+   *
+   * Must return the `html` string, otherwise the original will be used.
    *
    * @default undefined
    *
    * @example
    * ```
    * export default {
-   *   beforeRender: async ({html, config, render}) => {
+   *   beforeRender: async ({html, matter, config, posthtml, transform}) => {
    *     // do something...
    *     return html;
    *   }
    * }
    * ```
    */
-  beforeRender: beforeRenderType;
+  beforeRender: Events['beforeRender'];
 
   /**
   * Runs after the Template has been compiled, but before any Transformers have been applied.
-  * Exposes the rendered `html` string and the `config`. Must return the `html` string.
+  *
+  * Must return the `html` string, otherwise the original will be used.
   *
   * @default undefined
   *
   * @example
   * ```
   * export default {
-  *   afterRender: async ({html, config}) => {
+  *   afterRender: async ({html, matter, config, posthtml, transform}) => {
   *     // do something...
   *     return html;
   *   }
   * }
   * ```
   */
-  afterRender: afterRenderType;
+  afterRender: Events['afterRender'];
 
   /**
   * Runs after all Transformers have been applied, just before the final HTML is returned.
-  * Exposes the rendered `html` string and the `config`. Must return the `html` string.
+  *
+  * Must return the `html` string, otherwise the original will be used.
   *
   * @default undefined
   *
   * @example
   * ```
   * export default {
-  *   afterTransformers: async ({html, config, render}) => {
+  *   afterTransformers: async ({html, matter, config, posthtml, transform}) => {
   *     // do something...
   *     return html;
   *   }
   * }
   * ```
   */
-  afterTransformers: afterTransformersType;
+  afterTransformers: Events['afterTransformers'];
 
   /**
   * Runs after all Templates have been compiled and output to disk.
-  * The files parameter will contain the paths to all the files inside the `build.templates.destination.path` directory.
+  * `files` will contain the paths to all the files inside the `build.output.path` directory.
   *
   * @default undefined
   *
   * @example
   * ```
   * export default {
-  *   afterBuild: async ({files, config, render}) => {
+  *   afterBuild: async ({files, config, transform}) => {
   *     // do something...
   *   }
   * }
   * ```
   */
-  afterBuild: afterBuildType;
+  afterBuild: Events['afterBuild'];
+
+  [key: string]: any;
 }

package/types/events.d.ts

@@ -1,5 +1,165 @@
-export type beforeCreateType = (config: object) => Promise<void>;
-export type beforeRenderType = (html: string, config: object, render: (html: string, config: object) => Promise<string>) => Promise<string>;
-export type afterRenderType = ({ html, config }: { html: string, config: object }) => Promise<string>;
-export type afterTransformersType = ({ html, config, render }: { html: string, config: object, render: (html: string, config: object) => Promise<string> }) => Promise<string>;
-export type afterBuildType = ({ files, config, render }: { files: string[], config: object, render: (html: string, config: object) => Promise<string> }) => Promise<void>;
+import type Config from "./config";
+
+type PostHTMLType = (html: string, config: Config) => { html: string; config: Config };
+
+export default interface Events {
+  /**
+  * Runs after the Environment config has been computed, but before Templates are processed.
+  * Exposes the `config` object so you can further customize it.
+  *
+  * @default undefined
+  *
+  * @example
+  * ```
+  * export default {
+  *   beforeCreate: async ({config}) => {
+  *     // do something with `config`
+  *   }
+  * }
+  * ```
+  */
+  beforeCreate?: (params: { config: Config }) => void | Promise<void>;
+
+  /**
+  * Runs after the Template's config has been computed, but just before it is compiled.
+  *
+  * Must return the `html` string, otherwise the original will be used.
+  *
+  * @default undefined
+  *
+  * @example
+  * ```
+  * export default {
+  *   beforeRender: async ({html, matter, config, posthtml}) => {
+  *     // do something...
+  *     return html;
+  *   }
+  * }
+  * ```
+  */
+  beforeRender?: (params: {
+    /**
+     * The Template's HTML string.
+     */
+    html: string;
+    /**
+     * The Template's Front Matter.
+     */
+    matter: { [key: string]: string };
+    /**
+     * The Template's computed config.
+     */
+    config: Config;
+    /**
+     * A function to process an HTML string with PostHTML.
+     *
+     * @param {string} html The HTML string to process.
+     * @param {Config} config The Maizzle config object.
+     */
+    posthtml: PostHTMLType;
+  }) => string | Promise<string>;
+
+  /**
+  * Runs after the Template has been compiled, but before any Transformers have been applied.
+  *
+  * Must return the `html` string, otherwise the original will be used.
+  *
+  * @default undefined
+  *
+  * @example
+  * ```
+  * export default {
+  *   afterRender: async async ({html, matter, config, posthtml}) => {
+  *     // do something...
+  *     return html;
+  *   }
+  * }
+  * ```
+  */
+  afterRender?: (params: {
+    /**
+     * The Template's HTML string.
+     */
+    html: string;
+    /**
+     * The Template's Front Matter.
+     */
+    matter: { [key: string]: string };
+    /**
+     * The Template's computed config.
+     */
+    config: Config;
+    /**
+    * A function to process an HTML string with PostHTML.
+    *
+    * @param {string} html The HTML string to process.
+    * @param {Config} config The Maizzle config object.
+    */
+    posthtml: PostHTMLType;
+  }) => string | Promise<string>;
+
+  /**
+  * Runs after all Transformers have been applied, just before the final HTML is returned.
+  *
+  * Must return the `html` string, otherwise the original will be used.
+  *
+  * @default undefined
+  *
+  * @example
+  * ```
+  * export default {
+  *   afterTransformers: async ({html, matter, config, posthtml}) => {
+  *     // do something...
+  *     return html;
+  *   }
+  * }
+  * ```
+  */
+  afterTransformers?: (params: {
+    /**
+     * The Template's HTML string.
+     */
+    html: string;
+    /**
+     * The Template's Front Matter.
+     */
+    matter: { [key: string]: string };
+    /**
+     * The Template's computed config.
+     */
+    config: Config;
+    /**
+    * A function to process an HTML string with PostHTML.
+    *
+    * @param {string} html The HTML string to process.
+    * @param {Config} config The Maizzle config object.
+    */
+    posthtml: PostHTMLType;
+  }) => string | Promise<string>;
+
+  /**
+  * Runs after all Templates have been compiled and output to disk.
+  * `files` will contain the paths to all the files inside the `build.output.path` directory.
+  *
+  * @default undefined
+  *
+  * @example
+  * ```
+  * export default {
+  *   afterBuild: async ({files, config}) => {
+  *     // do something...
+  *   }
+  * }
+  * ```
+  */
+  afterBuild?: (params: {
+    /**
+     * An array of paths to all the files inside the `build.output.path` directory.
+     */
+    files: string[];
+    /**
+     * The Maizzle config object.
+     */
+    config: Config;
+  }) => string | Promise<string>;
+}

package/types/urlParameters.d.ts

@@ -1,7 +1,7 @@
 import type { URLParametersConfig as URLParamsConfig } from 'posthtml-url-parameters';
 
 export default interface URLParametersConfig {
-  [key: string]: any; // eslint-disable-line
+  [key: string]: any;
 
   _options?: {
     /**