@maizzle/framework 4.7.5 → 4.8.0

package/types/posthtml.d.ts

@@ -0,0 +1,195 @@
+import type PostHTMLFetchConfig from './fetch';
+import type ExpressionsConfig from './expressions';
+
+export interface PostHTMLOptions {
+  /**
+  Configure the PostHTML parser to process custom directives.
+
+  @default []
+  */
+  directives?: any[];
+
+  /**
+  Enable `xmlMode` if you're using Maizzle to output XML content, and not actual HTML.
+
+  @default false
+  */
+  xmlMode?: boolean;
+
+  /**
+  Decode entities in the HTML.
+
+  @default false
+  */
+  decodeEntities?: boolean;
+
+  /**
+  Output all tags in lowercase. Works only when `xmlMode` is disabled.
+
+  @default false
+  */
+  lowerCaseTags?: boolean;
+
+  /**
+  Output all attribute names in lowercase.
+
+  @default false
+  */
+  lowerCaseAttributeNames?: boolean;
+
+  /**
+  Recognize CDATA sections as text even if the `xmlMode` option is disabled.
+
+  @default false
+  */
+  recognizeCDATA?: boolean;
+
+  /**
+  Recognize self-closing tags.
+  Disabling this will cause rendering to stop at the first self-closing custom (non-HTML) tag.
+
+  @default true
+  */
+  recognizeSelfClosing?: boolean;
+
+  /**
+  If enabled, AST nodes will have a location property containing the `start` and `end` line and column position of the node.
+
+  @default false
+  */
+  sourceLocations?: boolean;
+
+  /**
+  Whether attributes with no values should render exactly as they were written, without `=""` appended.
+
+  @default true
+  */
+  recognizeNoValueAttribute?: boolean;
+
+  /**
+  Tell PostHTML to treat custom tags as self-closing.
+
+  @default []
+  */
+  singleTags?: string[] | RegExp[];
+
+  /**
+  Define the closing format for single tags.
+
+  @default 'default'
+  */
+  closingSingleTag?: 'tag' | 'slash';
+
+  /**
+  Whether to quote all attribute values.
+
+  @default true
+  */
+  quoteAllAttributes?: boolean;
+
+  /**
+  Replaces quotes in attribute values with `&quote;`.
+
+  @default true
+  */
+  replaceQuote?: boolean;
+
+  /**
+  Specify the style of quote around the attribute values.
+
+  @default 2
+
+  @example
+
+  `0` - Quote style is based on attribute values (an alternative for `replaceQuote` option)
+
+  ```
+  <img src="example.jpg" onload='testFunc("test")'>
+  ```
+
+  @example
+
+  `1` - Attribute values are wrapped in single quotes
+
+  ```
+  <img src='example.jpg' onload='testFunc("test")'>
+  ```
+
+  @example
+
+  `2` - Attribute values are wrapped in double quotes
+
+  ```
+  <img src="example.jpg" onload="testFunc("test")">
+  ```
+  */
+  quoteStyle?: 0 | 1 | 2;
+}
+
+export default interface PostHTMLConfig {
+  /**
+  Configure expressions.
+  */
+  expressions?: ExpressionsConfig;
+
+  /**
+  Configure PostHTML options.
+   */
+  options?: PostHTMLOptions;
+
+  /**
+  Additional PostHTML plugins that you would like to use.
+
+  These will run last, after components.
+
+  @default []
+
+  @example
+  ```
+  const spaceless = require('posthtml-spaceless')
+  module.exports = {
+    build: {
+      posthtml: {
+        plugins: [
+          spaceless()
+        ]
+      }
+    }
+  }
+  ```
+  */
+  plugins?: any[];
+
+  /**
+  Configure the `posthtml-mso` plugin.
+  */
+  outlook?: {
+    /**
+    The tag name to use for Outlook conditional comments.
+
+    @default 'outlook'
+
+    @example
+    ```
+    module.exports = {
+      build: {
+        posthtml: {
+          outlook: {
+            tag: 'mso'
+          }
+        }
+      }
+    }
+    // You now write <mso>...</mso> instead of <outlook>...</outlook>
+    ```
+    */
+    tag?: string;
+  };
+
+  /**
+  Configure the `<fetch>` tag behavior.
+
+  @default {}
+  */
+  fetch?: PostHTMLFetchConfig;
+}

package/types/removeUnusedCss.d.ts

@@ -0,0 +1,115 @@
+export default interface RemoveUnusedCSSConfig {
+  /**
+  Classes or IDs that you don't want removed.
+
+  @default []
+
+  @example
+  ```
+  module.exports = {
+    removeUnusedCSS: {
+      whitelist: ['.some-class', '.Mso*', '#*'],
+    }
+  }
+  ```
+  */
+  whitelist?: string[];
+
+  /**
+  Start and end delimiters for computed classes that you don't want removed.
+
+  @default [{heads: '{{', tails: '}}'}, {heads: '{%', tails: '%}'}]
+
+  @example
+  ```
+  module.exports = {
+    removeUnusedCSS: {
+      backend: [
+        { heads: '[[', tails: ']]' },
+      ]
+    }
+  }
+  ```
+  */
+  backend?: Array<Record<string, string>>;
+
+  /**
+  Whether to remove `<!-- HTML comments -->`.
+
+  @default true
+
+  @example
+  ```
+  module.exports = {
+    removeUnusedCSS: {
+      removeHTMLComments: false
+    }
+  }
+  ```
+  */
+  removeHTMLComments?: boolean;
+
+  /**
+  Whether to remove `/* CSS comments *\/`.
+
+  @default true
+
+  @example
+  ```
+  module.exports = {
+    removeUnusedCSS: {
+      removeCSSComments: false
+    }
+  }
+  ```
+  */
+  removeCSSComments?: boolean;
+
+  /**
+  Whether to remove classes that have been inlined.
+
+  @default undefined
+
+  @example
+  ```
+  module.exports = {
+    removeUnusedCSS: {
+      removeInlinedSelectors: false,
+    }
+  }
+  ```
+  */
+  removeInlinedSelectors?: boolean;
+
+  /**
+  List of strings representing start of a conditional comment that should not be removed.
+
+  @default ['[if', '[endif']
+
+  @example
+  ```
+  module.exports = {
+    removeUnusedCSS: {
+      doNotRemoveHTMLCommentsWhoseOpeningTagContains: ['[if', '[endif']
+    }
+  }
+  ```
+  */
+  doNotRemoveHTMLCommentsWhoseOpeningTagContains: string[];
+
+  /**
+  Rename all classes and IDs in both your `<style>` tags and your body HTML elements, to be as few characters as possible.
+
+  @default false
+
+  @example
+  ```
+  module.exports = {
+    removeUnusedCSS: {
+      uglify: true
+    }
+  }
+  ```
+  */
+  uglify?: boolean;
+}

package/types/render.d.ts

@@ -0,0 +1,130 @@
+import {
+  beforeRenderType,
+  afterRenderType,
+  afterTransformersType
+} from './events';
+import type Config from './config';
+import type TailwindConfig from './tailwind';
+
+export type RenderOutput = {
+  /**
+  The rendered HTML.
+  */
+  html: string;
+
+  /**
+  The Maizzle configuration object.
+  */
+  config: Config;
+};
+
+export default interface RenderOptions {
+  /**
+  A Maizzle configuration object.
+
+  @default {}
+
+  @example
+  ```
+  const Maizzle = require('@maizzle/framework');
+
+  Maizzle
+    .render(`html string`, {
+      maizzle: {
+        inlineCSS: true,
+      }
+    })
+    .then(({html, config}) => console.log(html, config))
+  ```
+  */
+  maizzle: Config;
+
+  /**
+  Tailwind CSS configuration object.
+
+  @default {}
+
+  @example
+  ```
+  const Maizzle = require('@maizzle/framework');
+
+  Maizzle
+    .render(`html string`, {
+      tailwind: {
+        config: './tailwind-custom.config.js',
+      },
+    })
+    .then(({html, config}) => console.log(html, config))
+  ```
+   */
+  tailwind?: TailwindConfig;
+
+  /**
+  A function that 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.
+
+  @default undefined
+
+  @example
+  ```
+  const Maizzle = require('@maizzle/framework');
+
+  Maizzle
+    .render(`html string`, {
+      beforeRender: (html, config) => {
+        // do something with html and config
+        return html;
+      },
+    })
+    .then(({html, config}) => console.log(html, config))
+  ```
+  */
+  beforeRender?: beforeRenderType;
+
+  /**
+  A function that runs after the Template has been compiled, but before any Transformers have been applied.
+
+  Exposes the rendered html string and the Templates' config.
+
+  @default undefined
+
+  @example
+  ```
+  const Maizzle = require('@maizzle/framework');
+
+  Maizzle
+    .render(`html string`, {
+      afterRender: (html, config) => {
+        // do something with html and config
+        return html;
+      },
+    })
+    .then(({html, config}) => console.log(html, config))
+  ```
+  */
+  afterRender?: afterRenderType;
+
+  /**
+  A function that runs after all Transformers have been applied, just before the final HTML is returned.
+
+  It exposes the Template's config, as well as the HTML.
+
+  @default undefined
+
+  @example
+  ```
+  const Maizzle = require('@maizzle/framework');
+
+  Maizzle
+    .render(`html string`, {
+      afterTransformers: (html, config) => {
+        // do something with html and config
+        return html;
+      },
+    })
+    .then(({html, config}) => console.log(html, config))
+  ```
+  */
+  afterTransformers?: afterTransformersType;
+}

package/types/tailwind.d.ts

@@ -0,0 +1,22 @@
+export default interface TailwindConfig {
+  /**
+  Path to the Tailwind config file.
+
+  @default 'tailwind.config.js'
+  */
+  config?: string;
+
+  /**
+  Path to your main CSS file, that will be compiled with Tailwind CSS.
+
+  @default 'src/css/tailwind.css'
+  */
+  css?: string;
+
+  /**
+  Pre-compiled CSS. Skip Tailwind CSS processing by providing your own CSS string.
+
+  @default ''
+  */
+  compiled?: string;
+}

package/types/templates.d.ts

@@ -0,0 +1,181 @@
+import type Config from './config';
+import type PlaintextConfig from './plaintext';
+
+export default interface TemplatesConfig {
+  /**
+  Directory where Maizzle should look for Templates to compile.
+
+  @default 'src/templates'
+
+  @example
+  ```
+  module.exports = {
+    build: {
+      templates: {
+        source: 'src/templates'
+      }
+    }
+  }
+  ```
+  */
+  source?:
+  | string
+  | Array<string | TemplatesConfig>
+  | ((config: Config) => string | string[]);
+
+  /**
+  Define what file extensions your Templates use.
+  Maizzle will only compile files from your `source` directory that have these extensions.
+
+  @default 'html'
+
+  @example
+  ```
+  module.exports = {
+    build: {
+      templates: {
+        filetypes: ['html', 'blade.php']
+      }
+    }
+  }
+  ```
+  */
+  filetypes?: string | string[];
+
+  /**
+  Define the output path for compiled Templates, and what file extension they should use.
+
+  @example
+  ```
+  module.exports = {
+    build: {
+      templates: {
+        destination: {
+          path: 'build_production',
+          extension: 'html'
+        }
+      }
+    }
+  }
+  ```
+  */
+  destination?: {
+    /**
+    Directory where Maizzle should output compiled Templates.
+
+    @default 'build_{env}'
+    */
+    path?: string;
+    /**
+    File extension to be used for compiled Templates.
+
+    @default 'html'
+    */
+    extension: string;
+  };
+
+  /**
+   * Source and destination directories for your asset files.
+   *
+   * @example
+   * ```
+   * module.exports = {
+   *   build: {
+   *     templates: {
+   *       assets: {
+   *         source: 'src/images',
+   *         destination: 'images'
+   *       }
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  assets?: {
+    /**
+     * Directory where Maizzle should look for asset files.
+     *
+     * @default ''
+     */
+    source?: string;
+    /**
+     * Directory where asset files should be copied to.
+     *
+     * @default 'assets'
+     */
+    destination?: string;
+  } | {
+    /**
+     * An array of objects specifying source and destination directories for asset files.
+     */
+    assets: Array<{
+      /**
+       * Directory where Maizzle should look for asset files.
+       */
+      source: string;
+      /**
+       * Directory where asset files should be copied to.
+       */
+      destination: string;
+    }>;
+  };
+
+  /**
+  Configure plaintext generation.
+
+  @example
+  ```
+  module.exports = {
+    build: {
+      plaintext: {
+        skipHtmlDecoding: true,
+        destination: {
+          path: 'dist/brand/plaintext',
+          extension: 'rtxt'
+        }
+      }
+    }
+  }
+  ```
+  */
+  plaintext?: boolean | PlaintextConfig;
+
+  /**
+  Paths to files or directories from your `source` that should _not_ be copied over to the build destination.
+
+  @default ['']
+
+  @example
+  ```
+  module.exports = {
+    build: {
+      templates: {
+        source: 'src/templates',
+        omit: ['1.html', 'archive/4.html'],
+      }
+    }
+  }
+  ```
+  */
+  omit?: string[];
+
+  /**
+  Paths to files relative to your `source` directory that should not be parsed.
+  They will be copied over to the build destination as-is.
+
+  @default ['']
+
+  @example
+  ```
+  module.exports = {
+    build: {
+      templates: {
+        source: 'src/templates',
+        skip: ['1.html', 'archive/3.html'],
+      }
+    }
+  }
+  ```
+  */
+  skip?: string | string[];
+}

package/types/urlParameters.d.ts

@@ -0,0 +1,39 @@
+import type {StringifyOptions} from 'query-string';
+
+export default interface URLParametersConfig {
+  [key: string]: any;
+
+  _options?: {
+    /**
+    Array of tag names to process. Only URLs inside `href` attributes of tags in this array will be processed.
+
+    @default ['a']
+
+    @example
+    ```
+    module.exports = {
+      urlParameters: {
+        _options: {
+          tags: ['a[href*="example.com"]'],
+        },
+        utm_source: 'maizzle',
+      }
+    }
+    ```
+    */
+    tags?: string[];
+
+    /**
+    By default, query parameters are appended only to valid URLs.
+    Disable strict mode to append parameters to any string.
+
+    @default true
+    */
+    strict?: boolean;
+
+    /**
+    Options to pass to the `query-string` library.
+    */
+    qs?: StringifyOptions;
+  };
+}