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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maizzle/framework",
-  "version": "5.0.0-beta.11",
+  "version": "5.0.0-beta.12",
   "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,6 +4,7 @@ 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'
 
@@ -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,13 +58,16 @@ 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,
@@ -78,13 +82,16 @@ 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,
@@ -111,13 +118,16 @@ 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,

package/types/config.d.ts

@@ -1,3 +1,4 @@
+import type Events from './events';
 import type BuildConfig from './build';
 import type MinifyConfig from './minify';
 import type PostHTMLConfig from './posthtml';
@@ -11,20 +12,11 @@ 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.
    */
@@ -488,83 +480,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,346 @@
-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";
+import type {
+  safeClassNames,
+  markdown,
+  preventWidows,
+  attributeToStyle,
+  inlineCSS,
+  shorthandCSS,
+  removeUnusedCSS,
+  purgeCSS,
+  removeAttributes,
+  addAttributes,
+  prettify,
+  applyBaseURL,
+  addUrlParams,
+  sixHEX,
+  minify,
+  replaceStrings,
+  plaintext,
+} from "./index";
+
+type PostHTMLType = (html: string, config: Config) => { html: string; config: Config };
+
+type TransformType = {
+  /**
+  * Normalize escaped character class names like `\:` or `\/` by replacing them with email-safe alternatives.
+  *
+  * @param {string} html The HTML string to normalize.
+  * @param {Record<string, string>} replacements A dictionary of replacements to apply.
+  * @returns {string} The normalized HTML string.
+  * @see https://maizzle.com/docs/transformers/safe-class-names
+  */
+  safeClassNames: typeof safeClassNames;
+  /**
+  * Compile Markdown to HTML.
+  *
+  * @param {string} input The Markdown string to compile.
+  * @param {MarkdownConfig} [options] A configuration object for the Markdown compiler.
+  * @returns {string} The compiled HTML string.
+  * @see https://maizzle.com/docs/transformers/markdown
+  */
+  markdown: typeof markdown;
+  /**
+  * Prevent widow words inside a tag by adding a `&nbsp;` between its last two words.
+  *
+  * @param {string} html The HTML string to process.
+  * @param {WidowWordsConfig} [options] A configuration object for the widow words transformer.
+  * @returns {string} The processed HTML string.
+  * @see https://maizzle.com/docs/transformers/widows
+  */
+  preventWidows: typeof preventWidows;
+  /**
+  * Duplicate HTML attributes to inline CSS.
+  *
+  * @param {string} html The HTML string to process.
+  * @param {AttributeToStyleSupportedAttributes[]} attributes An array of attributes to inline.
+  * @param {PostHTMLConfig} [posthtmlConfig] A configuration object for PostHTML.
+  * @returns {string} The processed HTML string.
+  * @see https://maizzle.com/docs/transformers/attribute-to-style
+  */
+  attributeToStyle: typeof attributeToStyle;
+  /**
+  * Inline CSS styles in an HTML string.
+  *
+  * @param {string} html The HTML string to process.
+  * @param {CSSInlineConfig} [options] A configuration object for the CSS inliner.
+  * @returns {string} The processed HTML string.
+  * @see https://maizzle.com/docs/transformers/inline-css
+  */
+  inlineCSS: typeof inlineCSS;
+  /**
+  * Rewrite longhand CSS inside style attributes with shorthand syntax.
+  * Only works with margin, padding and border, and only when all sides are specified.
+  *
+  * @param {string} html The HTML string to process.
+  * @returns {string} The processed HTML string.
+  * @see https://maizzle.com/docs/transformers/shorthand-css
+  */
+  shorthandCSS: typeof shorthandCSS;
+  /**
+  * Remove unused CSS from `<style>` tags and HTML elements.
+  *
+  * @param {string} html The HTML string to process.
+  * @param {PurgeCSSConfig} [options] A configuration object for `email-comb`.
+  * @returns {string} The processed HTML string.
+  * @see https://maizzle.com/docs/transformers/remove-unused-css
+  */
+  removeUnusedCSS: typeof removeUnusedCSS;
+  /**
+  * Remove HTML attributes from an HTML string.
+  *
+  * @param {string} html The HTML string to process.
+  * @param {string[] | Array<{ name: string; value: string | RegExp }>} [options] An array of attribute names to remove, or an array of objects with `name` and `value` properties.
+  * @returns {string} The processed HTML string.
+  * @see https://maizzle.com/docs/transformers/remove-attributes
+  */
+  removeAttributes: typeof removeAttributes;
+  /**
+  * Add attributes to elements in an HTML string.
+  *
+  * @param {string} html The HTML string to process.
+  * @param {Record<string, unknown>} [options] A dictionary of attributes to add.
+  * @returns {string} The processed HTML string.
+  * @see https://maizzle.com/docs/transformers/add-attributes
+  */
+  addAttributes: typeof addAttributes;
+  /**
+  * Pretty-print an HTML string.
+  *
+  * @param {string} html The HTML string to prettify.
+  * @param {HTMLBeautifyOptions} [options] A configuration object for `js-beautify`.
+  * @returns {string} The prettified HTML string.
+  * @see https://maizzle.com/docs/transformers/prettify
+  */
+  prettify: typeof prettify;
+  /**
+  * Prepend a string to sources and hrefs in an HTML string.
+  *
+  * @param {string} html The HTML string to process.
+  * @param {string | BaseURLConfig} [options] A string to prepend to sources and hrefs, or a configuration object for `posthtml-base-url`.
+  * @returns {string} The processed HTML string.
+  * @see https://maizzle.com/docs/transformers/base-url
+  */
+  applyBaseURL: typeof applyBaseURL;
+  /**
+  * Append parameters to URLs in an HTML string.
+  *
+  * @param {string} html The HTML string to process.
+  * @param {URLParametersConfig} [options] A configuration object for `posthtml-url-parameters`.
+  * @returns {string} The processed HTML string.
+  * @see https://maizzle.com/docs/transformers/url-parameters
+  */
+  addUrlParams: typeof addUrlParams;
+  /**
+  * Ensure that all HEX colors inside `bgcolor` and `color` attributes are defined with six digits.
+  *
+  * @param {string} html The HTML string to process.
+  * @returns {string} The processed HTML string.
+  * @see https://maizzle.com/docs/transformers/six-hex
+  */
+  sixHEX: typeof sixHEX;
+  /**
+  * Minify an HTML string, with email client considerations.
+  *
+  * @param {string} html The HTML string to minify.
+  * @param {MinifyConfig} [options] A configuration object for `html-minifier`.
+  * @returns {string} The minified HTML string.
+  * @see https://maizzle.com/docs/transformers/minify
+  */
+  minify: typeof minify;
+  /**
+  * Batch-replace strings in an HTML string.
+  *
+  * @param {string} html The HTML string to process.
+  * @param {Record<string, string>} [replacements] A dictionary of strings to replace.
+  * @returns {string} The processed HTML string.
+  * @see https://maizzle.com/docs/transformers/replace-strings
+  */
+  replaceStrings: typeof replaceStrings;
+  /**
+  * Generate a plaintext version of an HTML string.
+  * @param {string} html - The HTML string to convert to plaintext.
+  * @param {PlaintextConfig} [options] - A configuration object for the plaintext generator.
+  * @returns {Promise<string>} The plaintext version of the HTML string.
+  * @see https://maizzle.com/docs/plaintext
+  */
+  plaintext: typeof plaintext;
+};
+
+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, transform}) => {
+  *     // 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;
+    /**
+     * A collection of Maizzle Transformers.
+     */
+    transform: TransformType;
+  }) => 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, transform}) => {
+  *     // 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;
+    /**
+    * A collection of Maizzle Transformers.
+    */
+    transform: TransformType;
+  }) => 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, transform}) => {
+  *     // 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;
+    /**
+    * A collection of Maizzle Transformers.
+    */
+    transform: TransformType;
+  }) => 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, transform}) => {
+  *     // 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;
+    /**
+    * A collection of Maizzle Transformers.
+    */
+    transform: TransformType;
+  }) => string | Promise<string>;
+}