@maizzle/framework 4.8.7 → 5.0.0-beta.0

package/types/index.d.ts

@@ -1,90 +1,110 @@
-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 PostHTMLConfig from './posthtml';
+import type { RenderOutput } from './render';
+import type MarkdownConfig from './markdown';
+import type PurgeCSSConfig from './css/purge';
 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 CSSInlineConfig from './css/inline';
 import type WidowWordsConfig from './widowWords';
+import type { BaseURLConfig } from 'posthtml-base-url';
+import type { HTMLBeautifyOptions } from 'js-beautify'
+import type { URLParametersConfig } from 'posthtml-url-parameters';
+import type { AttributeToStyleSupportedAttributes } from './css/inline';
 
 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>;
+   * Compile an HTML string with Maizzle.
+   *
+   * @param {string} html The HTML string to render.
+   * @param {Config} [config] A Maizzle configuration object.
+   * @returns {Promise<RenderOutput>} The rendered HTML and the Maizzle configuration object.
+   */
+  function render(html: string, config?: Config): 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.
+   * Normalize escaped character class names like `\:` or `\/` by replacing them with email-safe alternatives.
+   *
+   * @param {string} html The HTML string to normalize.
+   * @param {Record<string, string>} replacements A dictionary of replacements to apply.
+   * @returns {string} The normalized HTML string.
+   * @see https://maizzle.com/docs/transformers/safe-class-names
    */
   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.
+   * Compile Markdown to HTML.
+   *
+   * @param {string} input The Markdown string to compile.
+   * @param {MarkdownConfig} [options] A configuration object for the Markdown compiler.
+   * @returns {string} The compiled HTML string.
+   * @see https://maizzle.com/docs/transformers/markdown
    */
-  function markdown(input: string, options?: MarkdownItOptions): string;
+  function markdown(input: string, options?: MarkdownConfig): 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.
-  */
+   * Prevent widow words inside a tag by adding a `&nbsp;` between its last two words.
+   *
+   * @param {string} html The HTML string to process.
+   * @param {WidowWordsConfig} [options] A configuration object for the widow words transformer.
+   * @returns {string} The processed HTML string.
+   * @see https://maizzle.com/docs/transformers/widows
+   */
   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.
-  */
+   * Duplicate HTML attributes to inline CSS.
+   *
+   * @param {string} html The HTML string to process.
+   * @param {AttributeToStyleSupportedAttributes[]} attributes An array of attributes to inline.
+   * @param {PostHTMLConfig} [posthtmlConfig] A configuration object for PostHTML.
+   * @returns {string} The processed HTML string.
+   * @see https://maizzle.com/docs/transformers/attribute-to-style
+   */
   function attributeToStyle(
     html: string,
-    options?: AttributeToStyleSupportedAttributes[]
+    attributes: AttributeToStyleSupportedAttributes[],
+    posthtmlConfig?: PostHTMLConfig
   ): 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;
+   * Inline CSS styles in an HTML string.
+   *
+   * @param {string} html The HTML string to process.
+   * @param {CSSInlineConfig} [options] A configuration object for the CSS inliner.
+   * @returns {string} The processed HTML string.
+   * @see https://maizzle.com/docs/transformers/inline-css
+   */
+  function inlineCSS(html: string, options?: CSSInlineConfig): 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.
-  */
+   * 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 process.
+   * @returns {string} The processed HTML string.
+   * @see https://maizzle.com/docs/transformers/shorthand-css
+   */
   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;
+   * Remove unused CSS from `<style>` tags and HTML elements.
+   *
+   * @param {string} html The HTML string to process.
+   * @param {PurgeCSSConfig} [options] A configuration object for `email-comb`.
+   * @returns {string} The processed HTML string.
+   * @see https://maizzle.com/docs/transformers/remove-unused-css
+   */
+  function removeUnusedCSS(html: string, options?: PurgeCSSConfig): 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.
-  */
+   * Remove HTML attributes from an HTML string.
+   *
+   * @param {string} html The HTML string to process.
+   * @param {string[] | Array<{ name: string; value: string | RegExp }>} [options] An array of attribute names to remove, or an array of objects with `name` and `value` properties.
+   * @returns {string} The processed HTML string.
+   * @see https://maizzle.com/docs/transformers/remove-attributes
+   */
   function removeAttributes(
     html: string,
     options?:
@@ -96,92 +116,104 @@ declare namespace MaizzleFramework {
   ): string;
 
   /**
-  Add attributes to elements in your HTML.
-
-  @param {string} html The HTML string to use.
-  @param {object} options Attributes to add.
-  */
+   * Add attributes to elements in an HTML string.
+   *
+   * @param {string} html The HTML string to process.
+   * @param {Record<string, unknown>} [options] A dictionary of attributes to add.
+   * @returns {string} The processed HTML string.
+   * @see https://maizzle.com/docs/transformers/add-attributes
+   */
   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;
+   * Pretty-print an HTML string.
+   *
+   * @param {string} html The HTML string to prettify.
+   * @param {HTMLBeautifyOptions} [options] A configuration object for `js-beautify`.
+   * @returns {string} The prettified HTML string.
+   * @see https://maizzle.com/docs/transformers/prettify
+   */
+  function prettify(html: string, options?: HTMLBeautifyOptions): 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.
-  */
+   * Prepend a string to sources and hrefs in an HTML string.
+   *
+   * @param {string} html The HTML string to process.
+   * @param {string | BaseURLConfig} [options] A string to prepend to sources and hrefs, or a configuration object for `posthtml-base-url`.
+   * @returns {string} The processed HTML string.
+   * @see https://maizzle.com/docs/transformers/base-url
+   */
   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.
-  */
+   * Append parameters to URLs in an HTML string.
+   *
+   * @param {string} html The HTML string to process.
+   * @param {URLParametersConfig} [options] A configuration object for `posthtml-url-parameters`.
+   * @returns {string} The processed HTML string.
+   * @see https://maizzle.com/docs/transformers/url-parameters
+   */
   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;
+   * Ensure that all HEX colors inside `bgcolor` and `color` attributes are defined with six digits.
+   *
+   * @param {string} html The HTML string to process.
+   * @returns {string} The processed HTML string.
+   * @see https://maizzle.com/docs/transformers/six-hex
+   */
+  function sixHEX(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.
-  */
+   * Minify an HTML string, with email client considerations.
+   *
+   * @param {string} html The HTML string to minify.
+   * @param {MinifyConfig} [options] A configuration object for `html-minifier`.
+   * @returns {string} The minified HTML string.
+   * @see https://maizzle.com/docs/transformers/minify
+   */
   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.
-  */
+   * Batch-replace strings in an HTML string.
+   *
+   * @param {string} html The HTML string to process.
+   * @param {Record<string, string>} [replacements] A dictionary of strings to replace.
+   * @returns {string} The processed HTML string.
+   * @see https://maizzle.com/docs/transformers/replace-strings
+   */
   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;
-  }>;
+   * Generate a plaintext version of an HTML string.
+   * @param {string} html - The HTML string to convert to plaintext.
+   * @param {PlaintextConfig} [options] - A configuration object for the plaintext generator.
+   * @returns {Promise<string>} The plaintext version of the HTML string.
+   * @see https://maizzle.com/docs/plaintext
+   */
+  function plaintext(html: string, options?: PlaintextConfig): Promise<string>;
 
   export {
     Config,
-    RenderOptions,
-    // Functions
-    addAttributes,
-    addURLParameters,
-    applyBaseURL,
-    attributeToStyle,
-    ensureSixHex,
-    inlineCSS,
+    render,
+    safeClassNames,
     markdown,
-    minify,
-    plaintext,
     preventWidows,
-    prettify,
-    removeAttributes,
+    attributeToStyle,
+    inlineCSS,
+    shorthandCSS,
     removeUnusedCSS,
-    render,
+    removeUnusedCSS as purgeCSS,
+    removeAttributes,
+    addAttributes,
+    prettify,
+    applyBaseURL,
+    addURLParameters as addUrlParams,
+    sixHEX,
+    minify,
     replaceStrings,
-    safeClassNames,
-    shorthandCSS
-  };
+    plaintext,
+  }
 }
 
 export = MaizzleFramework;

package/types/markdown.d.ts

@@ -1,31 +1,33 @@
-import type {Options as MarkdownItOptions} from 'markdown-it';
+import type { Options as MarkdownItOptions } from 'markdown-it';
 
 export default interface MarkdownConfig {
   /**
-  Path relative to which markdown files are imported.
-
-  @default './'
-  */
+   *  Path relative to which markdown files are imported.
+   *
+   *  @default './'
+   */
   root?: string;
 
   /**
-  Encoding for imported Markdown files.
-
-  @default 'utf8'
-  */
+   *  Encoding for imported Markdown files.
+   *
+   *  @default 'utf8'
+   */
   encoding?: string;
 
   /**
-  Options to pass to the `markdown-it` library.
-
-  @default {}
-  */
+   *  Options to pass to the `markdown-it` library.
+   *
+   *  @default {}
+   */
   markdownit?: MarkdownItOptions;
 
   /**
-  Plugins for the `markdown-it` library.
-
-  @default []
-  */
-  plugins?: any[];
+   *  Plugins for the `markdown-it` library.
+   *  @default []
+   */
+  plugins?: Array<{
+    plugin: string;
+    options: Record<string, unknown>;
+  }>;
 }

package/types/minify.d.ts

@@ -1,136 +1,138 @@
+import type { Opts } from 'html-crush';
+
 export default interface MinifyConfig {
   /**
-  Maximum line length. Works only when `removeLineBreaks` is `true`.
-
-  @default 500
-  */
-  lineLengthLimit?: number;
+   * Maximum line length. Works only when `removeLineBreaks` is `true`.
+   *
+   * @default 500
+   */
+  lineLengthLimit?: Opts['lineLengthLimit'];
 
   /**
-  Remove all line breaks from HTML when minifying.
-
-  @default true
-  */
-  removeLineBreaks?: boolean;
+   * Remove all line breaks from HTML when minifying.
+   *
+   * @default true
+   */
+  removeLineBreaks?: Opts['removeLineBreaks'];
 
   /**
-  Remove code indentation when minifying HTML.
-
-  @default true
+   * Remove code indentation when minifying HTML.
+   *
+   * @default true
   */
-  removeIndentations?: boolean;
+  removeIndentations?: Opts['removeIndentations'];
 
   /**
-  Remove `<!-- HTML comments -->` when minifying HTML.
-
-  `0` - don't remove any HTML comments
-
-  `1` - remove all comments except Outlook conditional comments
-
-  `2` - remove all comments, including Outlook conditional comments
-
-  @default false
-  */
-  removeHTMLComments?: boolean | number;
+   * Remove `<!-- HTML comments -->` when minifying HTML.
+   *
+   * `0` - don't remove any HTML comments
+   *
+   * `1` - remove all comments except Outlook conditional comments
+   *
+   * `2` - remove all comments, including Outlook conditional comments
+   *
+   * @default false
+   */
+  removeHTMLComments?: Opts['removeHTMLComments'];
 
   /**
-  Remove CSS comments when minifying HTML.
-
-  @default true
-  */
-  removeCSSComments?: boolean;
+   * Remove CSS comments when minifying HTML.
+   *
+   * @default true
+   */
+  removeCSSComments?: Opts['removeCSSComments'];
 
   /**
-  When any of given strings are encountered and `removeLineBreaks` is true, current line will be terminated.
-
-  @default
-  [
-    '</td',
-    '<html',
-    '</html',
-    '<head',
-    '</head',
-    '<meta',
-    '<link',
-    '<table',
-    '<script',
-    '</script',
-    '<!DOCTYPE',
-    '<style',
-    '</style',
-    '<title',
-    '<body',
-    '@media',
-    '</body',
-    '<!--[if',
-    '<!--<![endif',
-    '<![endif]'
-  ]
-  */
-  breakToTheLeftOf?: string[] | boolean | null;
+   * When any of given strings are encountered and `removeLineBreaks` is true, current line will be terminated.
+   *
+   * @default
+   * [
+   *   '</td',
+   *   '<html',
+   *   '</html',
+   *   '<head',
+   *   '</head',
+   *   '<meta',
+   *   '<link',
+   *   '<table',
+   *   '<script',
+   *   '</script',
+   *   '<!DOCTYPE',
+   *   '<style',
+   *   '</style',
+   *   '<title',
+   *   '<body',
+   *   '@media',
+   *   '</body',
+   *   '<!--[if',
+   *   '<!--<![endif',
+   *   '<![endif]'
+   * ]
+   */
+  breakToTheLeftOf?: Opts['breakToTheLeftOf'];
 
   /**
-  Some inline tags can accidentally introduce extra text.
-  The minifier will take extra precaution when minifying around these tags.
-
-  @default
-  [
-    'a',
-    'abbr',
-    'acronym',
-    'audio',
-    'b',
-    'bdi',
-    'bdo',
-    'big',
-    'br',
-    'button',
-    'canvas',
-    'cite',
-    'code',
-    'data',
-    'datalist',
-    'del',
-    'dfn',
-    'em',
-    'embed',
-    'i',
-    'iframe',
-    'img',
-    'input',
-    'ins',
-    'kbd',
-    'label',
-    'map',
-    'mark',
-    'meter',
-    'noscript',
-    'object',
-    'output',
-    'picture',
-    'progress',
-    'q',
-    'ruby',
-    's',
-    'samp',
-    'script',
-    'select',
-    'slot',
-    'small',
-    'span',
-    'strong',
-    'sub',
-    'sup',
-    'svg',
-    'template',
-    'textarea',
-    'time',
-    'u',
-    'tt',
-    'var',
-    'video',
-    'wbr'
-  ]
-  */
-  mindTheInlineTags?: string[] | boolean | null;
+   * Some inline tags can accidentally introduce extra text.
+   * The minifier will take extra precaution when minifying around these tags.
+   *
+   * @default
+   * [
+   *   'a',
+   *   'abbr',
+   *   'acronym',
+   *   'audio',
+   *   'b',
+   *   'bdi',
+   *   'bdo',
+   *   'big',
+   *   'br',
+   *   'button',
+   *   'canvas',
+   *   'cite',
+   *   'code',
+   *   'data',
+   *   'datalist',
+   *   'del',
+   *   'dfn',
+   *   'em',
+   *   'embed',
+   *   'i',
+   *   'iframe',
+   *   'img',
+   *   'input',
+   *   'ins',
+   *   'kbd',
+   *   'label',
+   *   'map',
+   *   'mark',
+   *   'meter',
+   *   'noscript',
+   *   'object',
+   *   'output',
+   *   'picture',
+   *   'progress',
+   *   'q',
+   *   'ruby',
+   *   's',
+   *   'samp',
+   *   'script',
+   *   'select',
+   *   'slot',
+   *   'small',
+   *   'span',
+   *   'strong',
+   *   'sub',
+   *   'sup',
+   *   'svg',
+   *   'template',
+   *   'textarea',
+   *   'time',
+   *   'u',
+   *   'tt',
+   *   'var',
+   *   'video',
+   *   'wbr'
+   * ]
+   */
+  mindTheInlineTags?: Opts['mindTheInlineTags'];
 }