@maizzle/framework 4.7.4 → 4.7.6

package/types/config.d.ts

@@ -0,0 +1,341 @@
+import type BuildConfig from './build';
+import type InlineCSSConfig from './inlineCss';
+import type RemoveUnusedCSSConfig from './removeUnusedCss';
+import type WidowWordsConfig from './widowWords';
+import type BaseURLConfig from './baseURL';
+import type URLParametersConfig from './urlParameters';
+import type {CoreBeautifyOptions} from 'js-beautify';
+import type MinifyConfig from './minify';
+import type MarkdownConfig from './markdown';
+import type EventsConfig from './events';
+
+export default interface Config {
+  [key: string]: any;
+
+  /**
+  Configure build settings.
+
+  @example
+  ```
+  module.exports = {
+    build: {
+      templates: TemplatesConfig,
+      tailwind: TailwindConfig,
+      layouts: LayoutsConfig,
+      components: ComponentsConfig,
+      posthtml: PostHTMLConfig,
+      browsersync: BrowserSyncConfig,
+      fail: 'silent' // or 'verbose'
+    }
+  }
+  ```
+  */
+  build: BuildConfig;
+
+  /**
+  Toggle the use of Transformers.
+
+  @default true
+
+  @example
+  ```
+  module.exports = {
+    applyTransformers: false,
+  }
+  ```
+  */
+  applyTransformers?: boolean;
+
+  /**
+  Configure CSS inlining.
+
+  To enable it with defaults, simply set it to `true`.
+  @example
+  ```js
+  module.exports = {
+    inlineCSS: true,
+  }
+  ```
+  */
+  inlineCSS?: boolean | InlineCSSConfig;
+
+  /**
+  Configure unused CSS purging.
+
+  To enable it with defaults, simply set it to `true`.
+  @example
+  ```
+  module.exports = {
+    removeUnusedCSS: true,
+  }
+  ```
+  */
+  removeUnusedCSS?: boolean | RemoveUnusedCSSConfig;
+
+  /**
+  Automatically remove HTML attributes.
+
+  By default, empty `style` and `class` attributes are removed.
+
+  @default ['style', 'class']
+
+  @example
+  ```
+  module.exports = {
+    removeAttributes: ['data-src']
+  }
+  ```
+  */
+  removeAttributes?:
+  | string[]
+  | Array<{
+    name: string;
+    value: string | RegExp;
+  }>;
+
+  /**
+  Prevent widow words inside a tag by adding a `&nbsp;` between its last two words.
+
+  @example
+  ```
+  module.exports = {
+    widowWords: true,
+  }
+  ```
+  */
+  widowWords?: WidowWordsConfig;
+
+  /**
+  [Add attributes](https://maizzle.com/docs/transformers/add-attributes) to elements in your HTML.
+
+  @default
+    {
+      table: {
+        cellpadding: 0,
+        cellspacing: 0,
+        role: 'none'
+      },
+      img: {
+        alt: ''
+      },
+    }
+  */
+  extraAttributes?: boolean | Record<string, unknown>;
+
+  /**
+  Normalize escaped character class names like `\:` or `\/` by replacing them with email-safe alternatives.
+
+  @example
+  ```
+  module.exports = {
+    safeClassNames: {
+      ':': '__',
+      '!': 'i-',
+    }
+  }
+  ```
+  */
+  safeClassNames?: boolean | Record<string, string>;
+
+  /**
+  Rewrite longhand CSS inside style attributes with shorthand syntax.
+  Only works with margin, padding and border, and only when all sides are specified.
+
+  @default []
+
+  @example
+  ```
+  module.exports = {
+    shorthandCSS: true, // or ['td', 'div'] to only apply to those tags
+  }
+  ```
+  */
+  shorthandCSS?: boolean | string[];
+
+  /**
+  Define a string that will be prepended to sources and hrefs in your HTML and CSS.
+
+  @example
+
+  Prepend to all sources and hrefs:
+
+  ```
+  module.exports = {
+    baseURL: 'https://cdn.example.com/'
+  }
+  ```
+
+  Prepend only to `src` attributes on image tags:
+
+  ```
+  module.exports = {
+    baseURL: {
+      url: 'https://cdn.example.com/',
+      tags: ['img'],
+    },
+  }
+  ```
+  */
+  baseURL?: string | BaseURLConfig;
+
+  /**
+  Transform text inside elements marked with custom attributes.
+
+  Filters work only on elements that contain only text.
+
+  @default {}
+
+  @example
+  ```
+  module.exports = {
+    filters: {
+      uppercase: str => str.toUpperCase()
+    }
+  }
+  ```
+  */
+  filters: Record<string, unknown>;
+
+  /**
+  Define variables outside of the `page` object.
+
+  @default {}
+
+  @example
+  ```
+  module.exports = {
+    locals: {
+      company: {
+        name: 'Spacely Space Sprockets, Inc.'
+      }
+    }
+  }
+  ```
+
+  `company` can be then used like this:
+
+  ```
+  <p>{{ company.name }}</p>
+  ```
+  */
+  locals?: Record<string, unknown>;
+
+  /**
+  Configure custom parameters to append to URLs.
+
+  @example
+  ```
+  module.exports = {
+    urlParameters: {
+      _options: {
+        tags: ['a'],
+        qs: {}, // options for the `query-string` library
+      },
+      utm_source: 'maizzle',
+      utm_campaign: 'Campaign Name',
+      utm_medium: 'email',
+      custom_parameter: 'foo',
+      '1stOfApril': 'bar',
+    }
+  }
+  ```
+  */
+  urlParameters?: URLParametersConfig;
+
+  /**
+  Ensure that all your HEX colors inside `bgcolor` and `color` attributes are defined with six digits.
+
+  @default true
+
+  @example
+  ```
+  module.exports = {
+    sixHex: false,
+  }
+  ```
+  */
+  sixHex?: boolean;
+
+  /**
+  [Pretty print](https://maizzle.com/docs/transformers/prettify) your HTML email code so that it's nicely indented and more human-readable.
+
+  @default undefined
+
+  @example
+  ```
+  module.exports = {
+    prettify: true,
+  }
+  ```
+  */
+  prettify?: boolean | CoreBeautifyOptions;
+
+  /**
+  Minify the compiled HTML email code.
+
+  @default false
+
+  @example
+  ```
+  module.exports = {
+    minify: true,
+  }
+  ```
+  */
+  minify?: boolean | MinifyConfig;
+
+  /**
+  Configure the Markdown parser.
+
+  @example
+
+  ```
+  module.exports = {
+    markdown: {
+      root: './', // A path relative to which markdown files are imported
+      encoding: 'utf8', // Encoding for imported Markdown files
+      markdownit: {}, // Options passed to markdown-it
+      plugins: [], // Plugins for markdown-it
+    }
+  }
+  ```
+  */
+  markdown?: MarkdownConfig;
+
+  /**
+  Batch-replace strings in your HTML.
+
+  @default {}
+
+  @example
+  ```
+  module.exports = {
+    replaceStrings: {
+      'replace this exact string': 'with this one',
+      '\\s?data-src=""': '', // remove empty data-src="" attributes
+    }
+  }
+  ```
+  */
+  replaceStrings?: Record<string, string>;
+
+  /**
+  When compiling your email templates, Maizzle goes through a series of steps like generating a Template config, rendering, or applying Transformers.
+  You can hook into the build process and manipulate it by using functions that run before or after some of these steps.
+
+  @default {}
+
+  @example
+  ```
+  module.exports = {
+    events: {
+      beforeRender: async (html, config) => {
+        // do something with html and config
+        return html;
+      },
+    }
+  }
+  ```
+  */
+  events?: EventsConfig;
+}

package/types/events.d.ts

@@ -0,0 +1,105 @@
+export type beforeCreateType = (config: any) => Promise<void>;
+export type beforeRenderType = (html: string, config: any) => Promise<string>;
+export type afterRenderType = (html: string, config: any) => Promise<string>;
+export type afterTransformersType = (html: string, config: any) => Promise<string>;
+export type afterBuildType = (files: any[], config: any) => Promise<void>;
+
+export default interface EventsConfig {
+  /**
+  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
+  ```
+  module.exports = {
+    events: {
+      beforeCreate: async (config) => {
+        // do something with `config`
+      }
+    }
+  }
+  ```
+  */
+  beforeCreate: beforeCreateType;
+
+  /**
+  Runs after the Template's config has been computed, but just before it is compiled.
+  It exposes the Template's config, as well as the HTML. Must return the `html` string.
+
+  @default undefined
+
+  @example
+  ```
+  module.exports = {
+    events: {
+      beforeRender: async (html, config) => {
+        // do something with html and config
+        return html;
+      }
+    }
+  }
+  ```
+  */
+  beforeRender: beforeRenderType;
+
+  /**
+  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.
+
+  @default undefined
+
+  @example
+  ```
+  module.exports = {
+    events: {
+      afterRender: async (html, config) => {
+        // do something with html and config
+        return html;
+      }
+    }
+  }
+  ```
+  */
+  afterRender: afterRenderType;
+
+  /**
+  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.
+
+  @default undefined
+
+  @example
+  ```
+  module.exports = {
+    events: {
+      afterTransformers: async (html, config) => {
+        // do something with html and config
+        return html;
+      }
+    }
+  }
+  ```
+  */
+  afterTransformers: afterTransformersType;
+
+  /**
+  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.
+
+  @default undefined
+
+  @example
+  ```
+  module.exports = {
+    events: {
+      afterBuild: async (files, config) => {
+        // do something with files or config
+      }
+    }
+  }
+  ```
+  */
+  afterBuild: afterBuildType;
+}

package/types/expressions.d.ts

@@ -0,0 +1,78 @@
+export default interface ExpressionsConfig {
+  /**
+  Define the starting and ending delimiters used for expressions.
+
+  @default ['{{', '}}']
+  */
+  delimiters?: string[];
+
+  /**
+  Define the starting and ending delimiters used for unescaped expressions.
+
+  @default ['{{{', '}}}']
+  */
+  unescapeDelimiters?: string[];
+
+  /**
+  Object containing data that will be available under the `page` object.
+
+  @default {}
+  */
+  locals?: Record<string, unknown>;
+
+  /**
+  Attribute name for `<script>` tags that contain locals.
+
+  @default 'locals'
+  */
+  localsAttr?: string;
+
+  /**
+  Whether to remove `<script>` tags that contain locals.
+
+  @default false
+  */
+  removeScriptLocals?: boolean;
+
+  /**
+  Tag names to be used for if/else statements.
+
+  @default ['if', 'elseif', 'else']
+  */
+  conditionalTags?: string[];
+
+  /**
+  Tag names to be used for switch statements.
+
+  @default ['switch', 'case', 'default']
+  */
+  switchTags?: string[];
+
+  /**
+  Tag names to be used for loops.
+
+  @default ['each', 'for']
+  */
+  loopTags?: string[];
+
+  /**
+  Tag names to be used for scopes.
+
+  @default ['scope']
+  */
+  scopeTags?: string[];
+
+  /**
+  Name of tag inside of which expression parsing is disabled.
+
+  @default 'raw'
+  */
+  ignoredTag?: string;
+
+  /**
+  Enabling strict mode will throw an error if an expression cannot be evaluated.
+
+  @default false
+  */
+  strictMode?: boolean;
+}

package/types/fetch.d.ts

@@ -0,0 +1,143 @@
+import type {Options as GotOptions} from 'got';
+import type ExpressionsConfig from './expressions';
+
+export default interface PostHTMLFetchConfig {
+  /**
+  Supported tag names.
+  Only tags from this array will be processed by the plugin.
+
+  @default ['fetch', 'remote']
+
+  @example
+  ```
+  module.exports = {
+    build: {
+      posthtml: {
+        fetch: {
+          tags: ['get']
+        }
+      }
+    }
+  }
+  ```
+  */
+  tags?: string[];
+
+  /**
+  String representing the attribute name containing the URL to fetch.
+
+  @default 'url'
+
+  @example
+  ```
+  module.exports = {
+    build: {
+      posthtml: {
+        fetch: {
+          attribute: 'from'
+        }
+      }
+    }
+  }
+  ```
+  */
+  attribute?: string;
+
+  /**
+  `posthtml-fetch` uses `got` to fetch data.
+  You can pass options directly to it, inside the `got` object.
+
+  @default {}
+
+  @example
+  ```
+  module.exports = {
+    build: {
+      posthtml: {
+        got: {
+          prefixUrl: '...'
+        }
+      }
+    }
+  }
+  ```
+  */
+  got?: GotOptions;
+
+  /**
+  When set to `true`, this option will preserve the `tag`, i.e. `<fetch>` around the response body.
+
+  @default false
+
+  @example
+  ```
+  module.exports = {
+    build: {
+      posthtml: {
+        fetch: {
+          preserveTag: true
+        }
+      }
+    }
+  }
+  ```
+  */
+  preserveTag?: boolean;
+
+  /**
+  Pass options to `posthtml-expressions`.
+
+  @default {}
+
+  @example
+  ```
+  module.exports = {
+    build: {
+      posthtml: {
+        fetch: {
+          expressions: {
+            delimiters: ['[[', ']]']
+          }
+        }
+      }
+    }
+  }
+  ```
+  */
+  expressions?: ExpressionsConfig;
+
+  /**
+  List of plugins that will be called after/before receiving and processing `locals`.
+
+  @default {}
+
+  @example
+  ```
+  module.exports = {
+    build: {
+      posthtml: {
+        fetch: {
+          plugins: {
+            after(tree) {
+              // Your plugin implementation
+            },
+            before: [
+              tree => {
+                // Your plugin implementation
+              },
+              tree => {
+                // ..
+              }
+            ]
+          }
+        }
+      }
+    }
+  }
+  ```
+  */
+  plugins?: {
+    after?: (tree: any) => void;
+    before?: Array<(tree: any) => void>;
+  };
+}