@maizzle/framework 4.7.5 → 4.7.6

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

package/types/index.d.ts

@@ -0,0 +1,187 @@
+import type {AttributeToStyleSupportedAttributes} from './inlineCss';
+import type BaseURLConfig from './baseURL';
+import type Config from './config';
+import type {CoreBeautifyOptions} from 'js-beautify';
+import type InlineCSSConfig from './inlineCss';
+import type {Options as MarkdownItOptions} from 'markdown-it';
+import type MinifyConfig from './minify';
+import type PlaintextConfig from './plaintext';
+import type RenderOptions from './render';
+import type {RenderOutput} from './render';
+import type RemoveUnusedCSSConfig from './removeUnusedCss';
+import type URLParametersConfig from './urlParameters';
+import type WidowWordsConfig from './widowWords';
+
+declare namespace MaizzleFramework {
+  /**
+  Compile an HTML string with Maizzle.
+
+  @param {string} html The HTML string to render.
+  @param {RenderOptions} [options] Options to pass to the renderer.
+  */
+  function render(html: string, options?: RenderOptions): Promise<RenderOutput>;
+
+  /**
+  Normalize escaped character class names like `\:` or `\/` by replacing them with email-safe alternatives.
+
+  @param {string} html The HTML string to render.
+  @param {object} replacements Customize replacements strategy.
+   */
+  function safeClassNames(html: string, replacements: Record<string, string>): string;
+
+  /**
+  Compile Markdown to HTML.
+
+  @param {string} input String to compile with Markdown.
+  @param {Options} [options] markdown-it options.
+   */
+  function markdown(input: string, options?: MarkdownItOptions): string;
+
+  /**
+  Prevent widow words inside a tag by adding a `&nbsp;` between its last two words.
+
+  @param {string} html The HTML string to render.
+  @param {WidowWordsConfig} [options] Options to pass to the transformer.
+  */
+  function preventWidows(html: string, options?: WidowWordsConfig): string;
+
+  /**
+  Duplicate HTML attributes to inline CSS.
+
+  @param {string} html The HTML string to render.
+  @param {AttributeToStyleSupportedAttributes} [options] Options to pass to the transformer.
+  */
+  function attributeToStyle(
+    html: string,
+    options?: AttributeToStyleSupportedAttributes[]
+  ): string;
+
+  /**
+  Inline CSS styles from `<style>` tags found in `<head>`.
+
+  @param {string} html The HTML string to render.
+  @param {InlineCSSConfig} [options] Options to pass to the transformer.
+  */
+  function inlineCSS(html: string, options?: InlineCSSConfig): string;
+
+  /**
+  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 render.
+  */
+  function shorthandCSS(html: string): string;
+
+  /**
+  Remove unused CSS from `<style>` tags and HTML elements.
+
+  @param {string} html The HTML string to use.
+  @param {RemoveUnusedCSSConfig} [options] Options to pass to the transformer.
+  */
+  function removeUnusedCSS(html: string, options?: RemoveUnusedCSSConfig): string;
+
+  /**
+  Automatically remove HTML attributes.
+  @param {string} html The HTML string to use.
+  @param options Either an array of attribute names, or an array of objects with `name` and `value` properties.
+  */
+  function removeAttributes(
+    html: string,
+    options?:
+    | string[]
+    | Array<{
+      name: string;
+      value: string | RegExp;
+    }>
+  ): string;
+
+  /**
+  Add attributes to elements in your HTML.
+
+  @param {string} html The HTML string to use.
+  @param {object} options Attributes to add.
+  */
+  function addAttributes(html: string, options?: Record<string, unknown>): string;
+
+  /**
+  Pretty print HTML code so that it's nicely indented and more human-readable.
+  @param {string} html The HTML string to prettify.
+  @param {CoreBeautifyOptions} [options] Options to pass to the prettifier.
+  */
+  function prettify(html: string, options?: CoreBeautifyOptions): string;
+
+  /**
+  Prepend a string to sources and hrefs in an HTML string.
+
+  @param {string} html The HTML string to use.
+  @param {BaseURLConfig} [options] Options to pass to the transformer.
+  */
+  function applyBaseURL(html: string, options?: string | BaseURLConfig): string;
+
+  /**
+  Append parameters to URLs in an HTML string.
+  @param {string} html The HTML string to use.
+  @param {URLParametersConfig} [options] Options to pass to the transformer.
+  */
+  function addURLParameters(html: string, options?: URLParametersConfig): string;
+
+  /**
+  Ensure that all your HEX colors inside `bgcolor` and `color` attributes are defined with six digits.
+
+  @param {string} html The HTML string to use.
+  */
+  function ensureSixHex(html: string): string;
+
+  /**
+  Minify a string of HTML code.
+
+  @param {string} html The HTML string to minify.
+  @param {MinifyConfig} [options] Options to pass to the minifier.
+  */
+  function minify(html: string, options?: MinifyConfig): string;
+
+  /**
+  Batch-replace strings in an HTML string.
+
+  @param {string} html The HTML string to use.
+  @param {object} replacements Strings to find and replace.
+  */
+  function replaceStrings(html: string, replacements?: Record<string, string>): string;
+
+  /**
+  Generate a plaintext version of an HTML string.
+
+  @param {string} html The HTML string to use.
+  @param {PlaintextConfig} [options] Options to pass to the plaintext generator.
+  */
+  function plaintext(html: string, options?: PlaintextConfig): Promise<{
+    html: string;
+    plaintext: string;
+    destination: string;
+  }>;
+
+  export {
+    Config,
+    RenderOptions,
+    // Functions
+    addAttributes,
+    addURLParameters,
+    applyBaseURL,
+    attributeToStyle,
+    ensureSixHex,
+    inlineCSS,
+    markdown,
+    minify,
+    plaintext,
+    preventWidows,
+    prettify,
+    removeAttributes,
+    removeUnusedCSS,
+    render,
+    replaceStrings,
+    safeClassNames,
+    shorthandCSS
+  };
+}
+
+export = MaizzleFramework;

package/types/inlineCss.d.ts

@@ -0,0 +1,207 @@
+export type AttributeToStyleSupportedAttributes =
+  | 'width'
+  | 'height'
+  | 'bgcolor'
+  | 'background'
+  | 'align'
+  | 'valign';
+
+export default interface InlineCSSConfig {
+  /**
+  Which CSS properties should be duplicated as what HTML attributes.
+
+  @default {}
+
+  @example
+  ```
+  module.exports = {
+    build: {
+      inlineCSS: {
+        styleToAttribute: {
+          'background-color': 'bgcolor',
+        }
+      }
+    }
+  }
+  ```
+  */
+  styleToAttribute?: Record<string, string>;
+
+  /**
+  Duplicate HTML attributes to inline CSS.
+
+  @default false
+
+  @example
+  ```
+  module.exports = {
+    build: {
+      inlineCSS: {
+        attributeToStyle: ['width', 'bgcolor', 'background']
+      }
+    }
+  }
+  ```
+  */
+  attributeToStyle?: boolean | AttributeToStyleSupportedAttributes[];
+
+  /**
+  HTML elements that will receive `width` attributes based on inline CSS width.
+
+  @default []
+
+  @example
+  ```
+  module.exports = {
+    build: {
+      inlineCSS: {
+        applyWidthAttributes: ['td', 'th']
+      }
+    }
+  }
+  ```
+  */
+  applyWidthAttributes?: string[];
+
+  /**
+  HTML elements that will receive `height` attributes based on inline CSS height.
+
+  @default []
+
+  @example
+  ```
+  module.exports = {
+    build: {
+      inlineCSS: {
+        applyHeightAttributes: ['td', 'th']
+      }
+    }
+  }
+  ```
+  */
+  applyHeightAttributes?: string[];
+
+  /**
+  List of elements that should only use `width` and `height`. Their inline CSS `width` and `height` will be removed.
+
+  @example
+  ```
+  module.exports = {
+    inlineCSS: {
+      keepOnlyAttributeSizes: {
+        width: ['img', 'video'],
+        height: ['img', 'video']
+      }
+    }
+  }
+  ```
+  */
+  keepOnlyAttributeSizes?: {
+    /**
+    List of elements that should only use the `width` HTML attribute (inline CSS width will be removed).
+
+    @default []
+
+    @example
+    ```
+    module.exports = {
+      inlineCSS: {
+        keepOnlyAttributeSizes: {
+          width: ['img', 'video'],
+        }
+      }
+    }
+    ```
+    */
+    width?: string[];
+    /**
+    List of elements that should only use the `height` HTML attribute (inline CSS height will be removed).
+
+    @default []
+
+    @example
+    ```
+    module.exports = {
+      inlineCSS: {
+        keepOnlyAttributeSizes: {
+          height: ['img', 'video']
+        }
+      }
+    }
+    ```
+    */
+    height?: string[];
+  };
+
+  /**
+  Remove inlined `background-color` CSS on elements containing a `bgcolor` HTML attribute.
+
+  @default false
+
+  @example
+  ```
+  module.exports = {
+    inlineCSS: {
+      preferBgColorAttribute: ['td'] // default: ['body', 'marquee', 'table', 'tbody', 'td', 'tfoot', 'th', 'thead', 'tr']
+    }
+  }
+  ```
+  */
+  preferBgColorAttribute?: boolean | string[];
+
+  /**
+  Array of CSS property names that should be excluded from the CSS inlining process. `--tw-shadow` is excluded by default.
+
+  @default []
+
+  @example
+  ```
+  module.exports = {
+    inlineCSS: {
+      excludedProperties: ['padding', 'padding-left']
+    }
+  }
+  ```
+  */
+  excludedProperties?: string[];
+
+  /**
+  An object where each value has a `start` and `end` to specify fenced code blocks that should be ignored during CSS inlining.
+
+  @default {EJS: {}, HBS: {}}
+
+  @example
+  ```
+  module.exports = {
+    EJS: { start: '<%', end: '%>' },
+    HBS: { start: '{{', end: '}}' },
+  }
+  ```
+  */
+  codeBlocks?: {
+    EJS?: Record<string, string>;
+    HBS?: Record<string, string>;
+  };
+
+  /**
+  Provide your own CSS to be inlined. Must be vanilla or pre-compiled CSS.
+
+  Existing `<style>` in your HTML tags will be ignored and their contents won't be inlined.
+
+  @default undefined
+
+  @example
+  ```
+  module.exports = {
+    inlineCSS: {
+      customCSS: `
+        .custom-class {
+          color: red;
+        }
+      `
+    }
+  }
+  ```
+   */
+  customCSS?: string;
+}