@maizzle/framework 5.0.0-beta.9 → 5.0.0

package/types/events.d.ts

@@ -1,5 +1,153 @@
-export type beforeCreateType = (config: object) => Promise<void>;
-export type beforeRenderType = (html: string, config: object, render: (html: string, config: object) => Promise<string>) => Promise<string>;
-export type afterRenderType = ({ html, config }: { html: string, config: object }) => Promise<string>;
-export type afterTransformersType = ({ html, config, render }: { html: string, config: object, render: (html: string, config: object) => Promise<string> }) => Promise<string>;
-export type afterBuildType = ({ files, config, render }: { files: string[], config: object, render: (html: string, config: object) => Promise<string> }) => Promise<void>;
+import type Config from "./config";
+
+export default interface Events {
+  /**
+  * 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
+  * ```
+  * export default {
+  *   beforeCreate: async ({config}) => {
+  *     // do something with `config`
+  *   }
+  * }
+  * ```
+  */
+  beforeCreate?: (params: {
+    /**
+     * The computed Maizzle config object.
+     */
+    config: Config
+  }) => void | Promise<void>;
+
+  /**
+  * Runs after the Template's config has been computed, but just before it is compiled.
+  *
+  * Must return the `html` string, otherwise the original will be used.
+  *
+  * @default undefined
+  *
+  * @example
+  * ```
+  * export default {
+  *   beforeRender: async ({html, matter, config, posthtml}) => {
+  *     // do something...
+  *     return html;
+  *   }
+  * }
+  * ```
+  */
+  beforeRender?: (params: {
+    /**
+     * The Template's HTML string.
+     */
+    html: string;
+    /**
+     * The Template's Front Matter data.
+     */
+    matter: { [key: string]: string };
+    /**
+     * The Template's computed config.
+     *
+     * This is the Environment config merged with the Template's Front Matter.
+     */
+    config: Config;
+  }) => string | Promise<string>;
+
+  /**
+  * Runs after the Template has been compiled, but before any Transformers have been applied.
+  *
+  * Must return the `html` string, otherwise the original will be used.
+  *
+  * @default undefined
+  *
+  * @example
+  * ```
+  * export default {
+  *   afterRender: async async ({html, matter, config, posthtml}) => {
+  *     // do something...
+  *     return html;
+  *   }
+  * }
+  * ```
+  */
+  afterRender?: (params: {
+    /**
+     * The Template's HTML string.
+     */
+    html: string;
+    /**
+     * The Template's Front Matter data.
+     */
+    matter: { [key: string]: string };
+    /**
+     * The Template's computed config.
+     *
+     * This is the Environment config merged with the Template's Front Matter.
+     */
+    config: Config;
+  }) => string | Promise<string>;
+
+  /**
+  * Runs after all Transformers have been applied, just before the final HTML is returned.
+  *
+  * Must return the `html` string, otherwise the original will be used.
+  *
+  * @default undefined
+  *
+  * @example
+  * ```
+  * export default {
+  *   afterTransformers: async ({html, matter, config, posthtml}) => {
+  *     // do something...
+  *     return html;
+  *   }
+  * }
+  * ```
+  */
+  afterTransformers?: (params: {
+    /**
+     * The Template's HTML string.
+     */
+    html: string;
+    /**
+     * The Template's Front Matter data.
+     */
+    matter: { [key: string]: string };
+    /**
+     * The Template's computed config.
+     *
+     * This is the Environment config merged with the Template's Front Matter.
+     */
+    config: Config;
+  }) => string | Promise<string>;
+
+  /**
+  * Runs after all Templates have been compiled and output to disk.
+  * `files` will contain the paths to all the files inside the `build.output.path` directory.
+  *
+  * @default undefined
+  *
+  * @example
+  * ```
+  * export default {
+  *   afterBuild: async ({config, files}) => {
+  *     // do something...
+  *   }
+  * }
+  * ```
+  */
+  afterBuild?: (params: {
+    /**
+     * The computed Maizzle config object.
+     */
+    config: Config;
+    /**
+     * An array of paths to all the files inside the `build.output.path` directory.
+     */
+    files: string[];
+  }) => string | Promise<string>;
+}

package/types/index.d.ts

@@ -37,10 +37,11 @@ declare namespace MaizzleFramework {
    *
    * @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
+   * @param {PostHTMLConfig} [posthtmlOptions] A configuration object for PostHTML.
+   * @returns {Promise<string>} The compiled HTML string.
+   * @see https://maizzle.com/docs/markdown#api
    */
-  function markdown(input: string, options?: MarkdownConfig): string;
+  function markdown(input: string, options?: MarkdownConfig, posthtmlOptions?: PostHTMLConfig): Promise<string>;
 
   /**
    * Prevent widow words inside a tag by adding a `&nbsp;` between its last two words.

package/types/posthtml.d.ts

@@ -1,5 +1,5 @@
 import type { Directive } from 'posthtml-parser';
-import type ExpressionsConfig from './expressions';
+import type { PostHTMLExpressions } from 'posthtml-expressions';
 
 export interface PostHTMLOptions {
   /**
@@ -128,9 +128,9 @@ export interface PostHTMLOptions {
 
 export default interface PostHTMLConfig {
   /**
-  Configure expressions.
+  Configure [posthtml-expressions](https://github.com/posthtml/posthtml-expressions) options.
   */
-  expressions?: ExpressionsConfig;
+  expressions?: PostHTMLExpressions;
 
   /**
   Configure PostHTML options.

package/types/urlParameters.d.ts

@@ -1,7 +1,7 @@
 import type { URLParametersConfig as URLParamsConfig } from 'posthtml-url-parameters';
 
 export default interface URLParametersConfig {
-  [key: string]: any; // eslint-disable-line
+  [key: string]: any;
 
   _options?: {
     /**

package/types/widowWords.d.ts

@@ -1,12 +1,10 @@
-import type { Opts } from 'string-remove-widows';
-
 export default interface WidowWordsConfig {
   /**
   The attribute name to use.
 
-  @default 'prevent-widows'
+  @default ['prevent-widows', 'no-widows']
   */
-  attrName?: string;
+  attributes?: Array<string>;
 
   /**
   Replace all widow word `nbsp;` instances with a single space.
@@ -14,45 +12,27 @@ export default interface WidowWordsConfig {
 
   @default false
   */
-  removeWidowPreventionMeasures?: Opts['removeWidowPreventionMeasures'];
-
-  /**
-  Convert the space entity to the `targetLanguage`.
-
-  @default true
-  */
-  convertEntities?: Opts['convertEntities'];
-
-  /**
-  Language to encode non-breaking spaces in.
-
-  @default 'html'
-  */
-  targetLanguage?: Opts['targetLanguage'];
-
-  /**
-  Should whitespace in front of dashes (-), n-dashes (–) or m-dashes (—) be replaced with a `&nbsp;`.
-
-  @default true
-  */
-  hyphens?: Opts['hyphens'];
+  createWidows?: Boolean;
 
   /**
   The minimum amount of words in a target string, in order to trigger the transformer.
 
   @default 3
   */
-  minWordCount?: Opts['minWordCount'];
-
-  /**
-  The minimum amount non-whitespace characters in a target string, in order to trigger the transformer.
-
-  @default 20
-  */
-  minCharCount?: Opts['minCharCount'];
+  minWords?: Number;
 
   /**
   Start/end pairs of strings that will prevent the transformer from removing widow words inside them.
-  */
-  ignore?: Opts['ignore'];
+
+  @default [
+    { start: '{{', end: '}}' },  // Handlebars, Liquid, Nunjucks, Twig, Jinja2, Mustache
+    { start: '{%', end: '%}' },  // Liquid, Nunjucks, Twig, Jinja2
+    { start: '<%=', end: '%>' }, // EJS, ERB
+    { start: '<%', end: '%>' },  // EJS, ERB
+    { start: '{$', end: '}' },   // Smarty
+    { start: '<\\?', end: '\\?>' }, // PHP
+    { start: '#{', end: '}' }    // Pug
+  ]
+  */
+  ignore?: Array<{ start: string; end: string }>;
 }

package/types/components.d.ts

@@ -1,195 +0,0 @@
-import type ExpressionsConfig from './expressions';
-import type { Options as PostHTMLParserOptions } from 'posthtml-parser';
-
-interface AnyObject {
-  [key: string]: string | AnyObject;
-}
-
-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 'yield'
-   */
-  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
-   * {
-   *  recognizeNoValueAttribute: true,
-   *  recognizeSelfClosing: true
-   * }
-   */
-  parserOptions?: PostHTMLParserOptions;
-
-  /**
-   * Configure [`posthtml-expressions`](https://github.com/posthtml/posthtml-expressions).
-   *
-   * @default
-   * {
-   *   strictMode: false,
-   *   missingLocal: '{local}',
-   *   locals: {
-   *     page: config, // the computed Maizzle config object
-   *   }
-   * }
-   */
-  expressions?: ExpressionsConfig;
-
-  /**
-   * PostHTML plugins to apply to each parsed component.
-   *
-   * @default []
-   */
-  plugins?: Array<() => void>;
-
-  /**
-   * Extra rules for the PostHTML plugin that is used by components to parse attributes.
-   *
-   * @default {}
-   */
-  attrsParserRules?: Record<string, AnyObject>;
-
-  /**
-   * 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/expressions.d.ts

@@ -1,100 +0,0 @@
-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;
-
-  /**
-  What to render when referencing a value that is not defined in `locals`.
-
-  By default, the string 'undefined' will be output.
-
-  @default undefined
-
-  @example
-
-  ```
-  // Output empty string if value is not defined
-  missingLocal: ''
-
-  // Output original reference if value is not defined
-  missingLocal: '{local}'
-
-  // Output custom string if value is not defined
-  missingLocal: 'ERR_NO_VALUE: {local}'
-  ```
-  */
-  missingLocal?: string;
-}