@maizzle/framework 4.7.5 → 4.7.6

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@maizzle/framework",
-  "version": "4.7.5",
+  "version": "4.7.6",
   "description": "Maizzle is a framework that helps you quickly build HTML emails with Tailwind CSS.",
   "license": "MIT",
   "main": "src/index.js",
-  "types": "src/index.d.ts",
+  "types": "types/index.d.ts",
   "bin": {
     "maizzle": "bin/maizzle"
   },
@@ -38,6 +38,7 @@
   },
   "files": [
     "src/**/*",
+    "types/**/*",
     "bin/*"
   ],
   "dependencies": {
@@ -78,6 +79,7 @@
     "tailwindcss": "^3.2.7"
   },
   "devDependencies": {
+    "@types/browser-sync": "^2.29.0",
     "@types/js-beautify": "^1.14.0",
     "@types/markdown-it": "^13.0.0",
     "ava": "^5.2.0",

package/types/baseUrl.d.ts

@@ -0,0 +1,79 @@
+export default interface BaseURLConfig {
+  /**
+  The URL to prepend.
+
+  @default undefined
+  */
+  url: string;
+
+  /**
+  Tags to apply the `url` to. When using this option, the `url` will only be prepended to the specified tags.
+
+  Maizzle uses a [custom set of tags](https://github.com/posthtml/posthtml-base-url/blob/main/lib/index.js#L6-L60) by default.
+
+  @example
+
+  Prepend `url` to all 'source'-like attribute values on image tags, like `src` and `srcset`:
+
+  ```
+  module.exports = {
+    baseURL: {
+      url: 'https://cdn.example.com/',
+      tags: ['img'],
+    },
+  }
+  ```
+
+  With more granular control:
+
+  ```
+  module.exports = {
+    baseURL: {
+      url: 'https://cdn.example.com/',
+      tags: {
+        img: {
+          src: true, // use the value of `url` above
+          srcset: 'https://bar.com/',
+        },
+      },
+    },
+  }
+  ```
+  */
+  tags?: string[] | Record<string, unknown>;
+
+  /**
+  Key-value pairs of attributes and the string to prepend to their existing value.
+
+  @default {}
+
+  @example
+
+  Prepend `https://example.com/` to all `data-url` attribute values:
+
+  ```
+  module.exports = {
+    baseURL: {
+      attributes: {
+        'data-url': 'https://example.com/',
+      },
+    },
+  }
+  ```
+  */
+  attributes?: Record<string, unknown>;
+
+  /**
+  Whether the string defined in `url` should be prepended to `url()` values in CSS `<style>` tags.
+
+  @default true
+  */
+  styleTag?: boolean;
+
+  /**
+  Whether the string defined in `url` should be prepended to `url()` values in inline CSS.
+
+  @default true
+  */
+  inlineCss?: boolean;
+}

package/types/build.d.ts

@@ -0,0 +1,74 @@
+import type LayoutsConfig from './layouts';
+import type PostHTMLConfig from './posthtml';
+import type TailwindConfig from './tailwind';
+import type TemplatesConfig from './templates';
+import type ComponentsConfig from './components';
+import type {Options as BrowserSyncConfig} from 'browser-sync';
+
+export default interface BuildConfig {
+  /**
+  Templates configuration.
+  */
+  templates: TemplatesConfig;
+
+  /**
+  Tailwind CSS configuration.
+  */
+  tailwind?: TailwindConfig;
+
+  /**
+  [DEPRECATED] Layouts configuration.
+  */
+  layouts?: LayoutsConfig;
+
+  /**
+  Components configuration.
+  */
+  components?: ComponentsConfig;
+
+  /**
+  PostHTML configuration.
+  */
+  posthtml?: PostHTMLConfig;
+
+  /**
+  Configure PostCSS
+   */
+  postcss?: {
+    /**
+    Additional PostCSS plugins that you would like to use.
+
+    @default []
+
+    @example
+    ```
+    const examplePlugin = require('postcss-example-plugin')
+    module.exports = {
+      build: {
+        postcss: {
+          plugins: [
+            examplePlugin()
+          ]
+        }
+      }
+    }
+    ```
+    */
+    plugins?: any[];
+  };
+
+  /**
+  Browsersync configuration.
+
+  When you run the `maizzle serve` command, Maizzle uses [Browsersync](https://browsersync.io/)
+  to start a local development server and open a directory listing of your emails in your default browser.
+  */
+  browsersync?: BrowserSyncConfig;
+
+  /**
+  Configure how build errors are handled when developing with the Maizzle CLI.
+
+  @default undefined
+  */
+  fail?: 'silent' | 'verbose';
+}

package/types/components.d.ts

@@ -0,0 +1,177 @@
+export default interface ComponentsConfig {
+  /**
+  Root path where to look for folders containing component files.
+
+  @default './'
+  */
+  root?: string;
+
+  /**
+  Paths where to look for component files. Must be relative to `root`.
+
+  @default ['src/components', 'src/layouts', 'src/templates']
+  */
+  folders?: string[];
+
+  /**
+  Prefix to use for component tags.
+
+  @default 'x-'
+  */
+  tagPrefix?: string;
+
+  /**
+  Tag name to be used in HTML when using a component.
+
+  @default 'component'
+  */
+  tag?: string;
+
+  /**
+  Attribute name to be used when referencing a component via its path.
+
+  @default 'src'
+  */
+  attribute?: string;
+
+  /**
+  File extension that component files must use.
+  Any other files will be ignored and not be made available as components.
+
+  @default 'html'
+  */
+  fileExtension?: string;
+
+  /**
+  Name of the tag that will be replaced with the content that is passed to the component.
+
+  @default 'content'
+  */
+  yield?: string;
+
+  /**
+  Name of the slot tag, where the content will be injected.
+
+  @default 'slot'
+  */
+  slot?: string;
+
+  /**
+  Name of the fill tag, where the content to be injected is defined.
+
+  @default 'fill'
+  */
+  fill?: string;
+
+  /**
+  String to use as a separator between the slot tag and its name.
+
+  @default ':'
+  */
+  slotSeparator?: string;
+
+  /**
+  Tag name for pushing content to a stack.
+
+  @default 'push'
+  */
+  push?: string;
+
+  /**
+  Tag name for popping (rendering) content from a stack.
+
+  @default 'stack'
+  */
+  stack?: string;
+
+  /**
+  Name of the props attribute to use in the `<script>` tag of a component.
+
+  @default 'props'
+  */
+  propsScriptAttribute?: string;
+
+  /**
+  Name of the object that will be used to store the props of a component.
+
+  @default 'props'
+  */
+  propsContext?: string;
+
+  /**
+  Name of the attribute that will be used to pass props to a component as JSON.
+
+  @default 'locals'
+  */
+  propsAttribute?: string;
+
+  /**
+  Name of the key to use when retrieving props passed to a slot via `$slots.slotName.props`.
+
+  @default 'props'
+  */
+  propsSlot?: string;
+
+  /**
+  Configure [`posthtml-parser`](https://github.com/posthtml/posthtml-parser).
+
+  @default {recognizeSelfClosing:true}
+  */
+  parserOptions?: Record<string, any>;
+
+  /**
+  Configure [`posthtml-expressions`](https://github.com/posthtml/posthtml-expressions).
+
+  @default {} // custom object
+  */
+  expressions?: Record<any, any>;
+
+  /**
+  PostHTML plugins to apply to each parsed component.
+
+  @default []
+  */
+  plugins?: any[];
+
+  /**
+  Extra rules for the PostHTML plugin that is used by components to parse attributes.
+
+  @default {}
+  */
+  attrsParserRules?: Record<any, any>;
+
+  /**
+  In strict mode, an error will be thrown if a component cannot be rendered.
+
+  @default true
+  */
+  strict?: boolean;
+
+  /**
+  Utility methods to be passed to `<script props>` in a component.
+
+  @default {merge: _.mergeWith, template: _.template}
+  */
+  utilities?: Record<string, unknown>;
+
+  /**
+  Define additional attributes that should be preserved for specific HTML elements.
+
+  @default {}
+  */
+  elementAttributes?: Record<string, void>;
+
+  /**
+  Attributes that should be preserved on all elements in components.
+
+  @default ['data-*']
+  */
+  safelistAttributes?: string[];
+
+  /**
+  Attributes that should be removed from all elements in components.
+
+  @default []
+  */
+  blacklistAttributes?: string[];
+}

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;
+}