diff --git a/types/mjml-core/index.d.ts b/types/mjml-core/index.d.ts new file mode 100644 index 0000000000..ccba07b676 --- /dev/null +++ b/types/mjml-core/index.d.ts @@ -0,0 +1,265 @@ +// Type definitions for mjml-core 4.7 +// Project: https://mjml.io +// Definitions by: Ian Edington +// Ryan Burr +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped + +/** + * The main parser for MJML. + * This version doesn't contain any of the core components registered in the 'mjml' package. + */ +export default function mjml2html(input: string | MJMLJsonObject, options?: MJMLParsingOptions): MJMLParseResults; + +/** + * Options passed as an object to the mjml2html function + * + * https://documentation.mjml.io/#inside-node-js + */ +export interface MJMLParsingOptions { + /** + * Default fonts imported in the HTML rendered by HTML + * ie. { 'Open Sans': 'https://fonts.googleapis.com/css?family=Open+Sans:300,400,500,700' } + * + * default: @see https://github.com/mjmlio/mjml/blob/master/packages/mjml-core/src/index.js + */ + fonts?: { [key: string]: string }; + + /** + * Option to keep comments in the HTML output + * default: true + */ + keepComments?: boolean; + + /** + * @deprecated use js-beautify directly after processing the MJML + * + * Option to beautify the HTML output + * default: false + */ + beautify?: boolean; + + /** + * @deprecated use html-minifier directly after processing the MJML + * + * Option to minify the HTML output + * + * default: false + */ + minify?: boolean; + /** + * @deprecated @see minify + * + * Options for html minifier, see mjml-cli documentation for more info + * Passed directly to html-minifier as options + * + * default: @see htmlMinify usage in mjml-core/src/index.js + */ + minifyOptions?: MJMLMinifyOptions; + + /** + * How to validate your MJML + * + * skip: your document is rendered without going through validation + * soft: your document is going through validation and is rendered, even if it has errors + * strict: your document is going through validation and is not rendered if it has any error + * + * default: soft + */ + validationLevel?: 'strict' | 'soft' | 'skip'; + + /** + * Full path of the specified file to use when resolving paths from mj-include components + * default: '.' + */ + filePath?: string; + /** + * The path or directory of the .mjmlconfig file + * default: process.cwd() + */ + mjmlConfigPath?: string; + + /** + * Use the config attribute defined in the .mjmlconfig file. + * The config passed into mjml2html overrides the .mjmlconfig. + * default: false + */ + useMjmlConfigOptions?: boolean; + + /** + * optional setting when inlining css, see mjml-cli documentation for more info + */ + juicePreserveTags?: { [index: string]: { start: string; end: string } }; + juiceOptions?: any; + + /** + * undocumented + * a function returning html skeleton + * default: see mjml-core/src/helpers/skeleton.js + */ + skeleton?: string | (() => string); + + actualPath?: string; + /** + * undocumented + * ignore mj-include elements + * default: false + */ + ignoreIncludes?: any; + /** + * see mjml-parser-xml + */ + preprocessors?: Array<((xml: string) => string)>; +} + +export interface MJMLMinifyOptions { + collapseWhitespace?: boolean; + minifyCSS?: boolean; + removeEmptyAttributes?: boolean; +} + +export interface MJMLParseResults { + html: string; + json: MJMLJsonObject; + errors: MJMLParseError[]; +} + +export interface MJMLParseError { + line: number; + message: string; + tagName: string; + formattedMessage: string; +} + +export type MJMLJsonObject = MJMLJsonWithChildren | MJMLJsonWithContent | MJMLJsonSelfClosingTag; + +export interface MJMLJsonWithChildren { + tagName: string; + attributes: object; + children: MJMLJsonObject[]; +} + +export interface MJMLJsonWithContent { + tagName: string; + attributes: object; + content: string; +} + +export interface MJMLJsonSelfClosingTag { + tagName: string; + attributes: object; +} + +/** + * An map of elements to handling component available to be used in mjml + */ +export const components: { [componentName: string]: Component | undefined }; + +/** + * Registers a component for use in mjml + */ +export function registerComponent(ComponentClass: typeof Component): void; + +export abstract class BodyComponent extends Component { + constructor(initialData: unknown); + + getStyles(): {}; + + /** + * takes a style attribute and tries to parse it's value + * ie. padding="1 2 3 4" + * getShorthandAttrValue("padding","left") => 1 + */ + getShorthandAttrValue(attribute: any, direction: any): number; + + getShorthandBorderValue(direction: any): number; + + getBoxWidths(): { + totalWidth: number; + borders: number; + paddings: number; + box: number; + }; + + htmlAttributes(attributes: any): any; + + styles(styles: any): any; + + renderChildren( + children?: [], + options?: { + props?: Component['props']; + renderer?: (component: Component) => any; + attributes?: Record; + rawXML?: boolean; + }, + ): string; +} + +export abstract class HeadComponent extends Component { + constructor(initialData: unknown); + + handlerChildren(): any; + + render(): string; +} + +export abstract class Component { + static getTagName(): any; + + static isRawElement(): boolean; + + static defaultAttributes: { [prop: string]: string | undefined }; + + props: { + children: any; + /** is first child */ + first: boolean; + index: number; + /** is last child */ + last: boolean; + /** number of sibling elements */ + sibling: number; + nonRawSiblings: number; + }; + attributes: Record; + context: any; + + constructor(initialData: unknown); + + getChildContext(): any; + + getAttribute(name: any): any; + + getContent(): any; + + /** + * Use if you want the CSS to be registered once + * + * @returns string css style string + */ + headStyle(breakpoint: number): string; + + /** + * Use if you need custom styles for every instance of a component + * + * @returns string css style string + */ + componentHeadStyle(breakpoint: number): string; + + /** + * If you want to return mjml from a component, it needs to be processed first, ie. + * + * render() { + * return this.renderMJML('hello world'); + * } + */ + renderMJML(mjml: string, options?: {}): string; + + /** + * Expected to return an html string + * @see renderMJML for returning an mjml string + */ + abstract render(): string; +} + +export function suffixCssClasses(classes: string, suffix: string): string; diff --git a/types/mjml-core/mjml-core-tests.ts b/types/mjml-core/mjml-core-tests.ts new file mode 100644 index 0000000000..0235b1131a --- /dev/null +++ b/types/mjml-core/mjml-core-tests.ts @@ -0,0 +1,42 @@ +import mjml2html, { BodyComponent, HeadComponent, Component, registerComponent } from 'mjml-core'; + +const simple_test = mjml2html(''); +const html = simple_test.html; +const errors = simple_test.errors; +let formattedMessage = errors[0].formattedMessage; +formattedMessage = 'force string test'; + +const minimal_opts_test = mjml2html('', { beautify: true }); +const validation_level_test = mjml2html('', { validationLevel: 'strict' }); +const filePath_test = mjml2html('', { filePath: '.' }); + +const jsonObject = { tagName: 'mjml', attributes: { width: '100px' }, content: 'test content' }; +const jsonObject_test = mjml2html(jsonObject); + +const minify_opts_test = mjml2html('hello world -// marpstar -// eiskalteschatten -// emrah88 +// Definitions by: aahoughton +// marpstar +// emrah88 +// IanEdington // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped -interface MJMLParsingOpts { - fonts?: { [key: string]: string; }; - keepComments?: boolean; - beautify?: boolean; - minify?: boolean; - validationLevel?: 'strict' | 'soft' | 'skip'; - filePath?: string; - minifyOptions?: MJMLMinifyOptions; -} - -interface MJMLParseError { - line: number; - message: string; - tagName: string; - formattedMessage: string; -} - -interface MJMLParseResults { - html: string; - errors: MJMLParseError[]; -} - -interface MJMLJsonObject { - tagName: string; - attributes: object; - children?: MJMLJsonObject[]; - content?: string; -} - -interface MJMLMinifyOptions { - collapseWhitespace?: boolean; - minifyCSS?: boolean; - removeEmptyAttributes?: boolean; -} - -declare function mjml2html(inp: string | MJMLJsonObject, opts?: MJMLParsingOpts): MJMLParseResults; +import mjml2html from 'mjml-core'; export = mjml2html; diff --git a/types/mjml/mjml-tests.ts b/types/mjml/mjml-tests.ts index 32caa8493b..aac807779a 100644 --- a/types/mjml/mjml-tests.ts +++ b/types/mjml/mjml-tests.ts @@ -1,17 +1,19 @@ -import mjml2html = require("mjml"); +import mjml2html = require('mjml'); -const simple_test = mjml2html(""); +const simple_test = mjml2html(''); const html = simple_test.html; const errors = simple_test.errors; let formattedMessage = errors[0].formattedMessage; -formattedMessage = "force string test"; +formattedMessage = 'force string test'; -const minimal_opts_test = mjml2html("", {beautify: true}); -const validation_level_test = mjml2html("", {validationLevel: "strict"}); -const filePath_test = mjml2html("", {filePath: "."}); +const minimal_opts_test = mjml2html('', { beautify: true }); +const validation_level_test = mjml2html('', { validationLevel: 'strict' }); +const filePath_test = mjml2html('', { filePath: '.' }); -const jsonObject = {tagName: "mjml", attributes: {width: "100px"}, content: "test content"}; +const jsonObject = { tagName: 'mjml', attributes: { width: '100px' }, content: 'test content' }; const jsonObject_test = mjml2html(jsonObject); -const minify_opts_test = mjml2html("