@maizzle/framework 5.0.0-beta.3 → 5.0.0-beta.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maizzle/framework",
-  "version": "5.0.0-beta.3",
+  "version": "5.0.0-beta.31",
   "description": "Maizzle is a framework that helps you quickly build HTML emails with Tailwind CSS.",
   "license": "MIT",
   "type": "module",
@@ -48,58 +48,60 @@
     "html-emails"
   ],
   "dependencies": {
-    "@csstools/css-calc": "^1.2.4",
+    "@csstools/css-calc": "^2.0.1",
     "@maizzle/cli": "next",
-    "cheerio": "^1.0.0-rc.12",
+    "cheerio": "^1.0.0",
     "chokidar": "^3.6.0",
     "cli-table3": "^0.6.5",
     "color-shorthand-hex-to-six-digit": "^5.0.16",
     "defu": "^6.1.4",
     "email-comb": "^7.0.21",
-    "express": "^4.19.2",
+    "express": "^4.21.0",
     "fast-glob": "^3.3.2",
     "gray-matter": "^4.0.3",
-    "html-crush": "^6.0.18",
+    "html-crush": "^6.0.19",
     "is-url-superb": "^6.1.0",
     "istextorbinary": "^9.5.0",
-    "juice": "^10.0.0",
+    "juice": "^11.0.0",
     "lodash-es": "^4.17.21",
-    "morphdom": "^2.7.3",
-    "ora": "^8.0.1",
+    "morphdom": "^2.7.4",
+    "ora": "^8.1.0",
     "pathe": "^1.1.2",
-    "postcss": "^8.4.39",
-    "postcss-custom-properties": "^13.3.12",
+    "postcss": "^8.4.49",
+    "postcss-custom-properties": "^14.0.4",
     "postcss-import": "^16.1.0",
     "postcss-safe-parser": "^7.0.0",
     "posthtml": "^0.16.6",
-    "posthtml-attrs-parser": "^1.1.0",
-    "posthtml-base-url": "^3.1.2",
-    "posthtml-component": "^1.1.0",
-    "posthtml-content": "^2.0.1",
-    "posthtml-extra-attributes": "^3.0.0",
-    "posthtml-markdownit": "^3.0.1",
-    "posthtml-mso": "^3.0.0",
-    "posthtml-parser": "^0.12.0",
-    "posthtml-postcss": "^1.0.0",
-    "posthtml-postcss-merge-longhand": "^3.1.0",
+    "posthtml-attrs-parser": "^1.1.1",
+    "posthtml-base-url": "^3.1.4",
+    "posthtml-component": "^2.0.0",
+    "posthtml-content": "^2.1.0",
+    "posthtml-expressions": "^1.11.4",
+    "posthtml-extra-attributes": "^3.1.0",
+    "posthtml-fetch": "^4.0.0",
+    "posthtml-markdownit": "^3.1.0",
+    "posthtml-mso": "^3.1.0",
+    "posthtml-parser": "^0.12.1",
+    "posthtml-postcss": "^1.0.2",
+    "posthtml-postcss-merge-longhand": "^3.1.2",
     "posthtml-render": "^3.0.0",
-    "posthtml-safe-class-names": "^4.0.2",
-    "posthtml-url-parameters": "^3.0.0",
+    "posthtml-safe-class-names": "^4.1.0",
+    "posthtml-url-parameters": "^3.1.0",
+    "posthtml-widows": "^1.0.0",
     "pretty": "^2.0.0",
-    "string-remove-widows": "^4.0.22",
     "string-strip-html": "^13.4.8",
-    "tailwindcss": "^3.4.5",
-    "ws": "^8.17.0"
+    "tailwindcss": "^3.4.15",
+    "ws": "^8.18.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^1.8.3",
+    "@biomejs/biome": "1.9.2",
     "@types/js-beautify": "^1.14.3",
-    "@types/markdown-it": "^14.1.1",
-    "@vitest/coverage-v8": "^2.0.1",
+    "@types/markdown-it": "^14.1.2",
+    "@vitest/coverage-v8": "^2.1.5",
     "supertest": "^7.0.0",
-    "vitest": "^2.0.1"
+    "vitest": "^2.1.5"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=18.20"
   }
 }

package/src/commands/build.js

@@ -4,7 +4,8 @@ import {
   copyFile,
   lstat,
   mkdir,
-  rm
+  rm,
+  cp,
 } from 'node:fs/promises'
 import path from 'pathe'
 import fg from 'fast-glob'
@@ -12,22 +13,50 @@ import { defu as merge } from 'defu'
 
 import get from 'lodash/get.js'
 import isEmpty from 'lodash-es/isEmpty.js'
-import { isBinary } from 'istextorbinary'
 
 import ora from 'ora'
 import pico from 'picocolors'
 import cliTable from 'cli-table3'
 
 import { render } from '../generators/render.js'
-import { formatTime } from '../utils/string.js'
+
+import {
+  formatTime,
+  getRootDirectories,
+  getFileExtensionsFromPattern,
+} from '../utils/string.js'
+
 import { getColorizedFileSize } from '../utils/node.js'
-import { readFileConfig } from '../utils/getConfigByFilePath.js'
+
 import {
   generatePlaintext,
   handlePlaintextTags,
   writePlaintextFile
 } from '../generators/plaintext.js'
 
+import { readFileConfig } from '../utils/getConfigByFilePath.js'
+
+/**
+ * Ensures that a directory exists, creating it if needed.
+ *
+ * @param {string} filePath - The path to the file to check.
+ */
+async function ensureDirectoryExistence(filePath) {
+  const dirname = path.dirname(filePath)
+  await mkdir(dirname, { recursive: true })
+}
+
+/**
+ * Copy a file from source to target.
+ *
+ * @param {string} source - The source file path.
+ * @param {string} target - The target file path.
+ */
+async function copyFileAsync(source, target) {
+  await ensureDirectoryExistence(target)
+  await copyFile(source, target)
+}
+
 /**
  * Compile templates and output to the build directory.
  * Returns a promise containing an object with files output and the config object.
@@ -41,7 +70,10 @@ export default async (config = {}) => {
   try {
     const startTime = Date.now()
 
-    // Compute config
+    /**
+     * Read the config file for this environment,
+     * merging it with the default config.
+     */
     config = await readFileConfig(config).catch(() => { throw new Error('Could not compute config') })
 
     /**
@@ -72,9 +104,12 @@ export default async (config = {}) => {
       head: ['File name', 'File size', 'Build time'].map(item => pico.bold(item)),
     })
 
-    // Determine paths of templates to build
-    const userFilePaths = get(config, 'build.content', 'src/templates/**/*.html')
-    const templateFolders = Array.isArray(userFilePaths) ? userFilePaths : [userFilePaths]
+    /**
+     * Check that templates to be built, actually exist
+     */
+    const contentPaths = get(config, 'build.content', ['src/templates/**/*.html'])
+
+    const templateFolders = Array.isArray(contentPaths) ? contentPaths : [contentPaths]
     const templatePaths = await fg.glob([...new Set(templateFolders)])
 
     // If there are no templates to build, throw error
@@ -82,37 +117,86 @@ export default async (config = {}) => {
       throw new Error(`No templates found in ${pico.inverse(templateFolders)}`)
     }
 
-    const baseDirs = templateFolders.filter(p => !p.startsWith('!')).map(p => {
-      const parts = p.split('/')
-      // remove the glob part (e.g., **/*.html):
-      return parts.filter(part => !part.includes('*')).join('/')
+    /**
+     * Copy source directories to destination
+     *
+     * Copies each `build.content` path to the `build.output.path` directory.
+     */
+    let from = get(config, 'build.output.from', ['src/templates', 'src'])
+
+    const globPathsToCopy = contentPaths.map(glob => {
+      // Keep negated paths as they are
+      if (glob.startsWith('!')) {
+        return glob
+      }
+
+      // Keep single-file sources as they are
+      if (!/\*/.test(glob)) {
+        return glob
+      }
+
+      // Update non-negated paths to target all files, avoiding duplication
+      return glob.replace(/\/\*\*\/\*\.\{.*?\}$|\/\*\*\/\*\.[^/]*$|\/*\.[^/]*$/, '/**/*')
     })
 
+    try {
+      from = Array.isArray(from) ? from : [from]
+
+      /**
+       * Copy files from source to destination
+       *
+       * The array/set conversion is to remove duplicates
+       */
+      for (const file of await fg(Array.from(new Set(globPathsToCopy)))) {
+        let relativePath
+        for (const dir of from) {
+          if (file.startsWith(dir)) {
+            relativePath = path.relative(dir, file)
+            break
+          }
+        }
+        if (!relativePath) {
+          relativePath = path.relative('.', file)
+        }
+
+        const targetPath = path.join(buildOutputPath, relativePath)
+        await copyFileAsync(file, targetPath)
+      }
+    } catch (error) {
+      console.error('Error while processing pattern:', error)
+    }
+
     /**
-     * Check for binary files
+     * Get a list of files to render, from the output directory
      *
-     * We store paths to binary files in a separate array, because we don't want
-     * to render them. These files will be treated as static files and will
-     * be copied directly to the output directory, just like the
-     * `build.static` folders.
+     * Uses all file extensions from non-negated glob paths in `build.content`
+     * to determine which files to render from the output directory.
      */
-    const binaryPaths = await fg.glob([...new Set(baseDirs.map(base => `${base}/**/*.*`))])
-      .then(paths => paths.filter(file => isBinary(file)))
+    const outputExtensions = new Set()
+
+    for (const pattern of contentPaths) {
+      outputExtensions.add(...getFileExtensionsFromPattern(pattern))
+    }
 
     /**
-     * Render templates
-     *
-     * Render each template and write the output to the output directory,
-     * preserving the relative path.
+     * Create a list of templates to compile
      */
-    for await (const templatePath of templatePaths) {
-      const templateBuildStartTime = Date.now()
+    const extensions = outputExtensions.size > 1
+      ? `{${[...outputExtensions].join(',')}}`
+      : [...outputExtensions][0] || 'html'
 
-      // Determine the base directory the template belongs to
-      const baseDir = baseDirs.find(base => templatePath.startsWith(base))
+    const templatesToCompile = await fg.glob(
+      path.join(
+        buildOutputPath,
+        `**/*.${extensions}`
+      )
+    )
 
-      // Compute the relative path
-      const relativePath = path.relative(baseDir, templatePath)
+    /**
+     * Render templates
+     */
+    for await (const templatePath of templatesToCompile) {
+      const templateBuildStartTime = Date.now()
 
       /**
        * Add the current template path to the config
@@ -122,8 +206,6 @@ export default async (config = {}) => {
        */
       config.build.current = {
         path: path.parse(templatePath),
-        baseDir,
-        relativePath,
       }
 
       const html = await readFile(templatePath, 'utf8')
@@ -141,12 +223,15 @@ export default async (config = {}) => {
       if (Boolean(plaintextConfig) || !isEmpty(plaintextConfig)) {
         const posthtmlOptions = get(rendered.config, 'posthtml.options', {})
 
-        const plaintext = await generatePlaintext(rendered.html, merge(plaintextConfig, posthtmlOptions))
-        rendered.html = await handlePlaintextTags(rendered.html, posthtmlOptions)
-        await writePlaintextFile(plaintext, rendered.config)
+        await writePlaintextFile(
+          await generatePlaintext(rendered.html, merge(plaintextConfig, posthtmlOptions)),
+          rendered.config
+        )
           .catch(error => {
             throw new Error(`Error writing plaintext file: ${error}`)
           })
+
+        rendered.html = await handlePlaintextTags(rendered.html, posthtmlOptions)
       }
 
       /**
@@ -158,8 +243,9 @@ export default async (config = {}) => {
        * We do this before generating plaintext, so that
        * any paths will already have been created.
        */
-      const outputPathFromConfig = get(rendered.config, 'permalink', path.join(buildOutputPath, relativePath))
+      const outputPathFromConfig = get(rendered.config, 'permalink', templatePath)
       const parsedOutputPath = path.parse(outputPathFromConfig)
+      // This keeps original file extension if no output extension is set
       const extension = get(rendered.config, 'build.output.extension', parsedOutputPath.ext.slice(1))
       const outputPath = `${parsedOutputPath.dir}/${parsedOutputPath.name}.${extension}`
 
@@ -175,62 +261,49 @@ export default async (config = {}) => {
       await writeFile(outputPath, rendered.html)
 
       /**
-       * Add file to CLI table for build summary logging
+       * Remove original file if its path is different
+       * from the final destination path.
        */
-      if (config.build.summary) {
-        table.push([
-          path.relative(get(rendered.config, 'build.output.path'), outputPath),
-          getColorizedFileSize(rendered.html),
-          formatTime(Date.now() - templateBuildStartTime)
-        ])
+      if (outputPath !== templatePath) {
+        await rm(templatePath)
       }
+
+      /**
+       * Add file to CLI table for build summary logging
+       */
+      table.push([
+        path.relative(get(rendered.config, 'build.output.path'), outputPath),
+        getColorizedFileSize(rendered.html),
+        formatTime(Date.now() - templateBuildStartTime)
+      ])
     }
 
     /**
      * Copy static files
      *
-     * Copy binary files that are alongside templates as well as
-     * files from `build.static`, to the output directory.
-     *
-     * TODO: support an array of objects with source and destination, i.e. static: [{ source: 'src/assets', destination: 'assets' }, ...]
+     * TODO: support an array of objects with source and destination,
+     * i.e. static: [{ source: 'src/assets', destination: 'assets' }, ...]
      */
+    const staticSourcePaths = getRootDirectories([...new Set(get(config, 'build.static.source', []))])
 
-    // Copy binary files that are alongside templates
-    for await (const binaryPath of binaryPaths) {
-      const relativePath = path.relative(get(config, 'build.current.baseDir'), binaryPath)
-      const outputPath = path.join(get(config, 'build.output.path'), get(config, 'build.static.destination'), relativePath)
-
-      await mkdir(path.dirname(outputPath), { recursive: true })
-      await copyFile(binaryPath, outputPath)
+    for await (const rootDir of staticSourcePaths) {
+      await cp(rootDir, path.join(buildOutputPath, get(config, 'build.static.destination')), { recursive: true })
     }
 
-    // Copy files from `build.static`
-    const staticSourcePaths = await fg.glob([...new Set(get(config, 'build.static.source', []))])
-      .then(paths => paths.filter(file => isBinary(file)))
-
-    if (!isEmpty(staticSourcePaths)) {
-      for await (const staticPath of staticSourcePaths) {
-        const relativePath = path.relative(get(config, 'build.current.baseDir'), staticPath)
-        const outputPath = path.join(get(config, 'build.output.path'), get(config, 'build.static.destination'), relativePath)
-
-        await mkdir(path.dirname(outputPath), { recursive: true })
-        await copyFile(staticPath, outputPath)
-      }
-    }
-
-    const compiledFiles = await fg.glob(path.join(config.build.output.path, '**/*'))
+    const allOutputFiles = await fg.glob(path.join(buildOutputPath, '**/*'))
 
     /**
      * Run `afterBuild` event
      */
     if (typeof config.afterBuild === 'function') {
-      await config.afterBuild({ files: compiledFiles, config, render })
+      await config.afterBuild({
+        config,
+        files: allOutputFiles,
+      })
     }
 
     /**
      * Log a build summary if enabled in the config
-     *
-     * Need to first clear the spinner
      */
 
     spinner.clear()
@@ -239,10 +312,10 @@ export default async (config = {}) => {
       console.log(table.toString() + '\n')
     }
 
-    spinner.succeed(`Build completed in ${formatTime(Date.now() - startTime)}`)
+    spinner.succeed(`Built ${table.length} template${table.length > 1 ? 's' : ''} in ${formatTime(Date.now() - startTime)}`)
 
     return {
-      files: compiledFiles,
+      files: allOutputFiles,
       config
     }
   } catch (error) {

package/src/generators/plaintext.js

@@ -3,8 +3,8 @@ import posthtml from 'posthtml'
 import get from 'lodash-es/get.js'
 import { defu as merge } from 'defu'
 import { stripHtml } from 'string-strip-html'
-import defaultConfig from '../posthtml/defaultConfig.js'
 import { writeFile, lstat, mkdir } from 'node:fs/promises'
+import { getPosthtmlOptions } from '../posthtml/defaultConfig.js'
 
 /**
  * Removes HTML tags from a given HTML string based on
@@ -46,7 +46,7 @@ const removeTags = ({ tag = 'not-plaintext', html = '', config = {} }) => {
     return tree.walk(process)
   }
 
-  const posthtmlOptions = merge(defaultConfig, config)
+  const posthtmlOptions = merge(config, getPosthtmlOptions())
 
   return posthtml([posthtmlPlugin()]).process(html, { ...posthtmlOptions }).then(res => res.html)
 }
@@ -95,7 +95,7 @@ export async function handlePlaintextTags(html = '', config = {}) {
     return tree.walk(process)
   }
 
-  const posthtmlOptions = merge(defaultConfig, config)
+  const posthtmlOptions = merge(config, getPosthtmlOptions())
 
   return posthtml([posthtmlPlugin()]).process(html, { ...posthtmlOptions }).then(res => res.html)
 }
@@ -134,7 +134,7 @@ export async function generatePlaintext(html = '', config = {}) {
   ).result
 }
 
-export async function writePlaintextFile(plaintext = '', templateConfig = {}) {
+export async function writePlaintextFile(plaintext = '', config = {}) {
   if (!plaintext) {
     throw new Error('Missing plaintext content.')
   }
@@ -149,25 +149,16 @@ export async function writePlaintextFile(plaintext = '', templateConfig = {}) {
    * Fall back to template's build output path and extension, for example:
    * `config.build.output.path`
    */
-  const plaintextConfig = get(templateConfig, 'plaintext')
-  let plaintextOutputPath = get(plaintextConfig, 'output.path', get(templateConfig, 'build.output.path'))
+  const plaintextConfig = get(config, 'plaintext')
+  let plaintextOutputPath = get(plaintextConfig, 'output.path', get(config, 'build.output.path'))
   const plaintextExtension = get(plaintextConfig, 'output.extension', 'txt')
 
   /**
-   * If `plaintext: true` (either from Front Matter or from config)
+   * If `plaintext: true` (either from Front Matter or from config),
+   * output plaintext file in the same location as the HTML file.
    */
   if (plaintextConfig === true) {
-    // If the template has a `permalink` key set in the FM
-    if (typeof templateConfig.permalink === 'string') {
-      // Output plaintext at the `permalink` path
-      plaintextOutputPath = templateConfig.permalink
-    } else {
-      // Output plaintext at the same directory as the HTML file
-      plaintextOutputPath = path.join(
-        get(templateConfig, 'build.output.path'),
-        get(templateConfig, 'build.current.relativePath')
-      )
-    }
+    plaintextOutputPath = get(config, 'build.output.path')
   }
 
   /**
@@ -182,11 +173,21 @@ export async function writePlaintextFile(plaintext = '', templateConfig = {}) {
   // No need to handle if it's an object, since we already set it to that initially
 
   /**
-   * If `plaintextOutputPath` is a file path, output file there
+   * If the template has a `permalink` key set in the FM, always output plaintext file there
+   */
+  if (typeof config.permalink === 'string') {
+    plaintextOutputPath = config.permalink
+  }
+
+  /**
+   * If `plaintextOutputPath` is a file path, output file there.
+   *
+   * The file will be output relative to the project root, and the extension
+   * doesn't matter, it will be replaced with `plaintextExtension`.
    */
   if (path.extname(plaintextOutputPath)) {
     // Ensure the target directory exists
-    await lstat(path.dirname(plaintextOutputPath)).catch(async () => {
+    await lstat(plaintextOutputPath).catch(async () => {
       await mkdir(path.dirname(plaintextOutputPath), { recursive: true })
     })
 
@@ -200,13 +201,15 @@ export async function writePlaintextFile(plaintext = '', templateConfig = {}) {
   }
 
   /**
-   * If `plaintextOutputPath` is a directory path, output file there, using the template's name
+   * If `plaintextOutputPath` is a directory path, output file there using the Template's name.
+   *
+   * The file will be output relative to the `build.output.path` directory.
    */
-  const templateFileName = get(templateConfig, 'build.current.path.name')
+  const templateFileName = get(config, 'build.current.path.name')
 
   plaintextOutputPath = path.join(
+    get(config, 'build.current.path.dir'),
     plaintextOutputPath,
-    get(templateConfig, 'build.current.path.dir'),
     templateFileName + '.' + plaintextExtension
   )
 

package/src/generators/render.js

@@ -4,6 +4,7 @@ import { cwd } from 'node:process'
 import { defu as merge } from 'defu'
 import expressions from 'posthtml-expressions'
 import { parseFrontMatter } from '../utils/node.js'
+import { getPosthtmlOptions } from '../posthtml/defaultConfig.js'
 import { process as compilePostHTML } from '../posthtml/index.js'
 import { run as useTransformers } from '../transformers/index.js'
 
@@ -40,7 +41,7 @@ export async function render(html = '', config = {}) {
       })
     ]
   )
-    .process(matter)
+    .process(matter, getPosthtmlOptions())
     .then(({ html }) => parseFrontMatter(`---${html}\n---`))
 
   const templateConfig = merge(matterData, config)
@@ -57,19 +58,21 @@ export async function render(html = '', config = {}) {
    *
    * @param {Object} options
    * @param {string} options.html - The HTML to be transformed
+   * @param {Object} options.matter - The front matter data
    * @param {Object} options.config - The current template config
-   * @param {function} options.render - The render function
    * @returns {string} - The transformed HTML, or the original one if nothing was returned
    */
   if (typeof templateConfig.beforeRender === 'function') {
     content = await templateConfig.beforeRender(({
       html: content,
+      matter: matterData,
       config: templateConfig,
-      render
     })) ?? content
   }
 
-  //  Compile PostHTML
+  /**
+   * Compile PostHTML
+   */
   const compiled = await compilePostHTML(content, templateConfig)
 
   /**
@@ -77,19 +80,18 @@ export async function render(html = '', config = {}) {
    *
    * @param {Object} options
    * @param {string} options.html - The HTML to be transformed
+   * @param {Object} options.matter - The front matter data
    * @param {Object} options.config - The current template config
-   * @param {function} options.render - The render function
    * @returns {string} - The transformed HTML, or the original one if nothing was returned
    */
   if (typeof templateConfig.afterRender === 'function') {
     compiled.html = await templateConfig.afterRender(({
       html: compiled.html,
-      config: templateConfig,
-      render
+      matter: matterData,
+      config: compiled.config,
     })) ?? compiled.html
   }
 
-  // Run Transformers
   /**
    * Run Transformers
    *
@@ -100,29 +102,28 @@ export async function render(html = '', config = {}) {
    * @returns {string} - The transformed HTML
    */
   if (templateConfig.useTransformers !== false) {
-    compiled.html = await useTransformers(compiled.html, templateConfig).then(({ html }) => html)
+    compiled.html = await useTransformers(compiled.html, compiled.config).then(({ html }) => html)
   }
 
-  // Run `afterTransformers` event
   /**
    * Run `afterTransformers` event
    *
    * @param {Object} options
    * @param {string} options.html - The HTML to be transformed
+   * @param {Object} options.matter - The front matter data
    * @param {Object} options.config - The current template config
-   * @param {function} options.render - The render function
    * @returns {string} - The transformed HTML, or the original one if nothing was returned
    */
   if (typeof templateConfig.afterTransformers === 'function') {
     compiled.html = await templateConfig.afterTransformers(({
       html: compiled.html,
-      config: templateConfig,
-      render
+      matter: matterData,
+      config: compiled.config,
     })) ?? compiled.html
   }
 
   return {
-    config: templateConfig,
+    config: compiled.config,
     html: compiled.html,
   }
 }

package/src/posthtml/defaultComponentsConfig.js

@@ -1,8 +1,8 @@
 export default {
   root: './',
-  folders: ['src/components', 'src/layouts', 'src/templates'],
-  fileExtension: 'html',
   tag: 'component',
+  fileExtension: 'html',
+  folders: ['src/components', 'src/layouts', 'src/templates'],
   expressions: {
     loopTags: ['each', 'for'],
     missingLocal: '{local}',

package/src/posthtml/defaultConfig.js

@@ -1,4 +1,14 @@
-export default {
-  recognizeNoValueAttribute: true,
-  recognizeSelfClosing: true
+import { defu as merge } from 'defu'
+
+export function getPosthtmlOptions(userConfigOptions = {}) {
+  return merge(
+    userConfigOptions,
+    {
+      recognizeNoValueAttribute: true,
+      recognizeSelfClosing: true,
+      directives: [
+        { name: '?php', start: '<', end: '>' },
+      ],
+    }
+  )
 }