@maizzle/framework 4.8.7 → 5.0.0-beta.0

package/types/config.d.ts

@@ -1,31 +1,82 @@
 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 PostHTMLConfig from './posthtml';
 import type MarkdownConfig from './markdown';
-import type EventsConfig from './events';
+import type { ProcessOptions } from 'postcss';
+import type PurgeCSSConfig from './css/purge';
+import type CSSInlineConfig from './css/inline';
+import type ComponentsConfig from './components';
+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;
+  [key: string]: any; // eslint-disable-line
+
+  /**
+   * Add or remove attributes from elements.
+   */
+  attributes?: {
+    /**
+     * Add attributes to specific elements.
+     *
+     * @default {}
+     *
+     * @example
+     * ```
+     * export default {
+     *   attributes: {
+     *     add: {
+     *       table: {
+     *         cellpadding: 0,
+     *         cellspacing: 0,
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    add?: Record<string, Record<string, string|number>>;
+
+    /**
+     * Remove attributes from elements.
+     *
+     * @default {}
+     *
+     * @example
+     * ```
+     * export default {
+     *   attributes: {
+     *     remove: ['width', 'height'],
+     *   }
+     * }
+     * ```
+     */
+    remove?: Record<string, string[]>;
+  }
 
   /**
   Configure build settings.
 
   @example
   ```
-  module.exports = {
+  export default {
     build: {
-      templates: TemplatesConfig,
-      tailwind: TailwindConfig,
-      layouts: LayoutsConfig,
       components: ComponentsConfig,
       posthtml: PostHTMLConfig,
-      browsersync: BrowserSyncConfig,
-      fail: 'silent' // or 'verbose'
+      tailwind: TailwindConfig,
+      templates: TemplatesConfig,
     }
   }
   ```
@@ -33,192 +84,327 @@ export default interface Config {
   build: BuildConfig;
 
   /**
-  Toggle the use of Transformers.
-
-  @default true
-
-  @example
-  ```
-  module.exports = {
-    applyTransformers: false,
-  }
-  ```
-  */
-  applyTransformers?: boolean;
-
-  /**
-  Configure CSS inlining.
+  Define a string that will be prepended to sources and hrefs in your HTML and CSS.
 
-  To enable it with defaults, simply set it to `true`.
   @example
-  ```js
-  module.exports = {
-    inlineCSS: true,
-  }
-  ```
-  */
-  inlineCSS?: boolean | InlineCSSConfig;
 
-  /**
-  Configure unused CSS purging.
+  Prepend to all sources and hrefs:
 
-  To enable it with defaults, simply set it to `true`.
-  @example
   ```
-  module.exports = {
-    removeUnusedCSS: true,
+  export default {
+    baseURL: 'https://cdn.example.com/'
   }
   ```
-  */
-  removeUnusedCSS?: boolean | RemoveUnusedCSSConfig;
-
-  /**
-  Automatically remove HTML attributes.
 
-  By default, empty `style` and `class` attributes are removed.
-
-  @default ['style', 'class']
+  Prepend only to `src` attributes on image tags:
 
-  @example
   ```
-  module.exports = {
-    removeAttributes: ['data-src']
+  export default {
+    baseURL: {
+      url: 'https://cdn.example.com/',
+      tags: ['img'],
+    },
   }
   ```
   */
-  removeAttributes?:
-  | string[]
-  | Array<{
-    name: string;
-    value: string | RegExp;
-  }>;
+  baseURL?: string | BaseURLConfig;
 
   /**
-  Prevent widow words inside a tag by adding a `&nbsp;` between its last two words.
+   * Configure components.
+   */
+  components?: ComponentsConfig;
 
-  @example
-  ```
-  module.exports = {
-    widowWords: true,
+  /**
+   * Configure how CSS is handled.
+   */
+  css: {
+    /**
+     * Configure CSS inlining.
+     */
+    inline?: CSSInlineConfig;
+
+    /**
+     * Configure CSS purging.
+     */
+    purge?: PurgeCSSConfig;
+
+    /**
+     * Normalize escaped character class names like `\:` or `\/` by replacing them
+     * with email-safe alternatives.
+     *
+     * @example
+     * ```
+     * export default {
+     *   css: {
+     *     safeClassNames: {
+     *       ':': '__',
+     *       '!': 'i-',
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    safeClassNames?: boolean | Record<string, string>;
+
+    /**
+     * Ensure that all your HEX colors inside `bgcolor` and `color` attributes are defined with six digits.
+     *
+     * @default true
+     *
+     * @example
+     * ```
+     * export default {
+     *   css: {
+     *     sixHex: false,
+     *   }
+     * }
+     * ```
+     */
+    sixHex?: boolean;
+
+    /**
+     * 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
+     * ```
+     * export default {
+     *   css: {
+     *     shorthand: {
+     *       tags: ['td', 'div'],
+     *     } // or shorthand: true
+     *   }
+     * }
+     * ```
+     */
+    shorthand?: boolean | Record<string, string[]>;
+
+    /**
+     * Use a custom Tailwind CSS configuration object.
+     *
+     */
+    tailwind?: TailwindConfig;
   }
-  ```
-  */
-  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>;
+   * Transform text inside elements marked with custom attributes.
+   * Filters work only on elements that contain only text.
+   *
+   * @default {}
+   *
+   * @example
+   * ```
+   * export default {
+   *   filters: {
+   *     uppercase: str => str.toUpperCase(),
+   *   }
+   * }
+   * ```
+   */
+  filters: boolean | Record<string, (str: string) => string>;
 
   /**
-  Normalize escaped character class names like `\:` or `\/` by replacing them with email-safe alternatives.
-
-  @example
-  ```
-  module.exports = {
-    safeClassNames: {
-      ':': '__',
-      '!': 'i-',
-    }
-  }
-  ```
-  */
-  safeClassNames?: boolean | Record<string, string>;
+   * Define variables outside of the `page` object.
+   *
+   * @default {}
+   *
+   * @example
+   * ```
+   * export default {
+   *   locals: {
+   *     company: {
+   *       name: 'Spacely Space Sprockets, Inc.'
+   *     }
+   *   }
+   * }
+   * ```
+   *
+   * `company` can then be used like this:
+   *
+   * ```
+   * <p>{{ company.name }}</p>
+   * ```
+   */
+  locals?: Record<string, any>; // eslint-disable-line
 
   /**
-  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[];
+   * Configure the Markdown parser.
+   *
+   * @example
+   *
+   * ```
+   * export default {
+   *   markdown: {
+   *     root: './', // 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;
 
   /**
-  Define a string that will be prepended to sources and hrefs in your HTML and CSS.
-
-  @example
-
-  Prepend to all sources and hrefs:
+   * Minify the compiled HTML email code.
+   *
+   * @default false
+   *
+   * @example
+   * ```
+   * export default {
+   *   minify: true,
+   * }
+   * ```
+   */
+  minify?: boolean | MinifyConfig;
 
-  ```
-  module.exports = {
-    baseURL: 'https://cdn.example.com/'
-  }
-  ```
+  /**
+  Configure the `posthtml-mso` plugin.
+  */
+  outlook?: {
+    /**
+    The tag name to use for Outlook conditional comments.
 
-  Prepend only to `src` attributes on image tags:
+    @default 'outlook'
 
-  ```
-  module.exports = {
-    baseURL: {
-      url: 'https://cdn.example.com/',
-      tags: ['img'],
-    },
-  }
-  ```
-  */
-  baseURL?: string | BaseURLConfig;
+    @example
+    ```
+    export default {
+      outlook: {
+        tag: 'mso'
+      }
+    }
+    // You now write <mso>...</mso> instead of <outlook>...</outlook>
+    ```
+    */
+    tag?: string;
+  };
 
   /**
-  Transform text inside elements marked with custom attributes.
+   * Configure plaintext generation.
+   */
+  plaintext?: PlaintextConfig;
 
-  Filters work only on elements that contain only text.
-
-  @default {}
+  /**
+   * PostHTML configuration.
+   */
+  posthtml?: PostHTMLConfig;
 
-  @example
-  ```
-  module.exports = {
-    filters: {
-      uppercase: str => str.toUpperCase()
-    }
-  }
-  ```
-  */
-  filters: Record<string, unknown>;
+  /**
+   * Configure PostCSS
+   */
+  postcss?: {
+    /**
+     * Additional PostCSS plugins that you would like to use.
+     * @default []
+     * @example
+     * ```
+     * import examplePlugin from 'postcss-example-plugin'
+     * export default {
+     *   postcss: {
+     *     plugins: [
+     *       examplePlugin()
+     *     ]
+     *   }
+     * }
+     * ```
+     */
+    plugins?: Array<() => void>;
+
+    /**
+     * PostCSS options
+     * @default {}
+     * @example
+     * ```
+     * export default {
+     *  postcss: {
+     *   options: {
+     *     map: true
+     *   }
+     * }
+     * ```
+     */
+    options?: ProcessOptions;
+  };
 
   /**
-  Define variables outside of the `page` object.
+   * [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
+   * ```
+   * export default {
+   *   prettify: true,
+   * }
+   * ```
+   */
+  prettify?: boolean | CoreBeautifyOptions;
 
-  @default {}
+  /**
+   * Batch-replace strings in your HTML.
+   *
+   * @default {}
+   *
+   * @example
+   * ```
+   * export default {
+   *   replaceStrings: {
+   *     'replace this exact string': 'with this one',
+   *     '\\s?data-src=""': '', // remove empty data-src="" attributes
+   *   }
+   * }
+   * ```
+   */
+  replaceStrings?: Record<string, string>;
 
-  @example
-  ```
-  module.exports = {
-    locals: {
-      company: {
-        name: 'Spacely Space Sprockets, Inc.'
-      }
-    }
+  /**
+   * Configure local server settings.
+   */
+  server?: {
+    /**
+     * Port to run the local server on.
+     *
+     * @default 3000
+     */
+    port?: number;
+
+    /**
+     * Enable HMR-like local development.
+     * When enabled, Maizzle will watch for changes in your templates
+     * and inject them into the browser without a full page reload.
+     *
+     * @default true
+     */
+    hmr?: boolean;
+
+    /**
+     * Enable synchronized scrolling across devices.
+     *
+     * @default false
+     */
+    syncScroll?: boolean;
+
+    /**
+     * Paths to watch for changes.
+     * When a file in these paths changes, Maizzle will do a full rebuild.
+     *
+     * @default []
+     */
+    watch?: string[];
+
+    /**
+     * Toggle reporting compiled file size in the console.
+     *
+     * @default false
+     */
+    reportFileSize?: boolean;
   }
-  ```
-
-  `company` can be then used like this:
-
-  ```
-  <p>{{ company.name }}</p>
-  ```
-  */
-  locals?: Record<string, unknown>;
 
   /**
   Configure custom parameters to append to URLs.
@@ -243,99 +429,125 @@ export default interface Config {
   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,
-  }
-  ```
+   * Enable or disable all Transformers.
+   *
+   * @default true
+   *
+   * @example
+   * ```
+   * export default {
+   *   useTransformers: false,
+   * }
+   * ```
   */
-  sixHex?: boolean;
+  useTransformers?: 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;
+   * Prevent widow words inside a tag by adding a `&nbsp;` between its last two words.
+   *
+   * @default
+   * {
+   *   minWordCount: 3,
+   *   attrName: 'prevent-widows'
+   * }
+   *
+   * @example
+   * ```
+   * export default {
+   *   widowWords: {
+   *     minWordCount: 5,
+   *   },
+   * }
+   * ```
+   */
+  widowWords?: WidowWordsConfig;
 
   /**
-  Minify the compiled HTML email code.
-
-  @default false
-
-  @example
-  ```
-  module.exports = {
-    minify: true,
-  }
-  ```
+  * 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`
+  *   }
+  * }
+  * ```
   */
-  minify?: boolean | MinifyConfig;
+  beforeCreate: beforeCreateType;
 
   /**
-  Configure the Markdown parser.
+   * 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.
+   *
+   * @default undefined
+   *
+   * @example
+   * ```
+   * export default {
+   *   beforeRender: async ({html, config, render}) => {
+   *     // do something...
+   *     return html;
+   *   }
+   * }
+   * ```
+   */
+  beforeRender: beforeRenderType;
 
-  @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
-    }
-  }
-  ```
+  /**
+  * 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
+  * ```
+  * export default {
+  *   afterRender: async ({html, config}) => {
+  *     // do something...
+  *     return html;
+  *   }
+  * }
+  * ```
   */
-  markdown?: MarkdownConfig;
+  afterRender: afterRenderType;
 
   /**
-  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
-    }
-  }
-  ```
+  * 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
+  * ```
+  * export default {
+  *   afterTransformers: async ({html, config, render}) => {
+  *     // do something...
+  *     return html;
+  *   }
+  * }
+  * ```
   */
-  replaceStrings?: Record<string, string>;
+  afterTransformers: afterTransformersType;
 
   /**
-  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;
-      },
-    }
-  }
-  ```
+  * 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
+  * ```
+  * export default {
+  *   afterBuild: async ({files, config, render}) => {
+  *     // do something...
+  *   }
+  * }
+  * ```
   */
-  events?: EventsConfig;
+  afterBuild: afterBuildType;
 }