@maizzle/framework 4.8.7 → 5.0.0-beta.0

package/src/generators/plaintext.js

@@ -1,118 +1,219 @@
-const path = require('path')
-const posthtml = require('posthtml')
-const {get, merge} = require('lodash')
-const {stripHtml} = require('string-strip-html')
-const defaultConfig = require('./posthtml/defaultConfig')
-
-const self = {
-  removeCustomTags: (tag, html, config = {}) => {
-    const posthtmlOptions = get(config, 'build.posthtml.options', {})
-
-    const posthtmlPlugin = () => tree => {
-      const process = node => {
-        if (!node.tag) {
-          return node
-        }
-
-        if (node.tag === tag) {
-          return {
-            tag: false,
-            content: ['']
-          }
-        }
-
-        if (Array.isArray(tag) && tag.includes(node.tag)) {
-          return {
-            tag: false,
-            content: ['']
-          }
-        }
+import path from 'pathe'
+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'
+
+/**
+ * Removes HTML tags from a given HTML string based on
+ * a specified tag name or an array of tag names.
+ *
+ * @param {Object} options - The options object.
+ * @param {string|string[]} [options.tag='not-plaintext'] - The tag name or an array of tag names to remove from the HTML.
+ * @param {string} [options.html=''] - The HTML string from which to remove the tags.
+ * @param {Object} [options.config={}] - PostHTML options.
+ * @returns {string} - The HTML string with the specified tags removed.
+ */
+const removeTags = ({ tag = 'not-plaintext', html = '', config = {} }) => {
+  /**
+   * If the HTML string is empty, return it as is
+   */
+  if (!html) {
+    return html
+  }
 
+  const posthtmlPlugin = () => tree => {
+    const process = node => {
+      if (!node.tag) {
         return node
       }
 
-      return tree.walk(process)
-    }
-
-    return posthtml([posthtmlPlugin()]).process(html, {...posthtmlOptions, sync: true}).html
-  },
-  handleCustomTags: (html, config = {}) => {
-    const posthtmlOptions = merge(defaultConfig, get(config, 'build.posthtml.options', {}))
-
-    const posthtmlPlugin = () => tree => {
-      const process = node => {
-        if (node.tag === 'plaintext') {
-          return {
-            tag: false,
-            content: ['']
-          }
-        }
-
-        if (node.tag === 'not-plaintext') {
-          return {
-            tag: false,
-            content: tree.render(node.content)
-          }
+      /**
+       * If the tag is a string and it matches the node tag, remove it
+       */
+      if (node.tag === tag) {
+        return {
+          tag: false,
+          content: ['']
         }
-
-        return node
       }
 
-      return tree.walk(process)
+      return node
     }
 
-    return posthtml([posthtmlPlugin()]).process(html, {...posthtmlOptions, sync: true}).html
-  },
-  generate: async (html, destination, config = {}) => {
-    const configDestinationPath = get(config, 'destination.path')
-    const extension = get(config, 'destination.extension', 'txt')
+    return tree.walk(process)
+  }
 
-    const strippedHTML = self.removeCustomTags('not-plaintext', html, config)
+  const posthtmlOptions = merge(defaultConfig, config)
 
-    const plaintext = stripHtml(strippedHTML, {
-      dumpLinkHrefsNearby: {
-        enabled: true
-      },
-      stripTogetherWithTheirContents: ['script', 'style', 'xml'],
-      ...config
-    }).result
+  return posthtml([posthtmlPlugin()]).process(html, { ...posthtmlOptions }).then(res => res.html)
+}
 
-    html = self.handleCustomTags(html, config)
+/**
+ * Handles custom <plaintext> tags and replaces their content based on the tag name.
+ *
+ * @param {Object} options - The options object.
+ * @param {string} [options.html=''] - The HTML string containing custom tags to be processed.
+ * @param {Object} [options.config={}] - PostHTML options.
+ * @returns {string} - The modified HTML string after processing custom tags.
+ */
+export async function handlePlaintextTags(html = '', config = {}) {
+  /**
+   * If the HTML string is empty, return early
+   */
+  if (!html) {
+    return html
+  }
 
-    // If we set plaintext.destination.path in config/fm
-    if (configDestinationPath) {
+  const posthtmlPlugin = () => tree => {
+    const process = node => {
       /**
-       * Using a file path will generate a single plaintext file,
-       * no matter how many templates there are.
-       *
-       * It will be based on the last-processed template.
+       * Remove <plaintext> tags and their content from the HTML
        */
-      if (path.extname(configDestinationPath)) {
-        destination = configDestinationPath
-
-        return {html, plaintext, destination}
+      if (node.tag === 'plaintext') {
+        return {
+          tag: false,
+          content: ['']
+        }
       }
 
       /**
-       * Using a directory-like path for plaintext.destination.path
+       * Replace <not-plaintext> tags with their content
        */
-      destination = path.join(configDestinationPath, path.basename(config.filepath, path.extname(config.filepath)) + '.' + extension)
+      if (node.tag === 'not-plaintext') {
+        return {
+          tag: false,
+          content: tree.render(node.content)
+        }
+      }
 
-      return {html, plaintext, destination}
+      return node
     }
 
-    /**
-     * Use template's `permalink` Front Matter key,
-     * fall back to the original `destination`.
-     */
-    destination = get(config, 'permalink', destination)
+    return tree.walk(process)
+  }
+
+  const posthtmlOptions = merge(defaultConfig, config)
+
+  return posthtml([posthtmlPlugin()]).process(html, { ...posthtmlOptions }).then(res => res.html)
+}
+
+/**
+ * Generate a plaintext representation from the provided HTML.
+ *
+ * @param {Object} options - The options object.
+ * @param {string} [options.html=''] - The HTML string to convert to plaintext.
+ * @param {Object} [options.config={}] - Configuration object.
+ * @returns {Promise<string>|void} - The generated plaintext as a string.
+ */
+export async function generatePlaintext(html = '', config = {}) {
+  const { posthtml: posthtmlOptions, ...stripOptions } = config
+
+  /**
+   * Remove <not-plaintext> tags and their content from the HTML.
+   * `config` is an object containing PostHTML options.
+   */
+  html = await removeTags({ tag: 'not-plaintext', html, config: posthtmlOptions })
+
+  /**
+   * Return the plaintext representation from the stripped HTML.
+   * The `dumpLinkHrefsNearby` option is enabled by default.
+   */
+  return stripHtml(
+    html,
+    merge(
+      stripOptions,
+      {
+        dumpLinkHrefsNearby: {
+          enabled: true,
+        },
+      },
+    )
+  ).result
+}
+
+export async function writePlaintextFile(plaintext = '', templateConfig = {}) {
+  if (!plaintext) {
+    throw new Error('Missing plaintext content.')
+  }
+
+  if (typeof plaintext !== 'string') {
+    throw new Error('Plaintext content must be a string.')
+  }
 
-    if (typeof destination === 'string') {
-      destination = path.join(path.dirname(destination), path.basename(destination, path.extname(destination)) + '.' + extension)
+  /**
+   * Get plaintext output path config, i.e `config.plaintext.destination.path`
+   *
+   * 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 plaintextExtension = get(plaintextConfig, 'output.extension', 'txt')
+
+  /**
+   * If `plaintext: true` (either from Front Matter or from config)
+   */
+  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')
+      )
     }
+  }
 
-    return {html, plaintext, destination}
+  /**
+   * If `plaintext: path/to/file.ext` in the FM
+   * Can't work if set in config.js as file path, because it would be the same for all templates
+   * We check later if it's a dir path, won't work if it's a file path
+   */
+  if (typeof plaintextConfig === 'string') {
+    plaintextOutputPath = plaintextConfig
   }
-}
 
-module.exports = self
+  // 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 (path.extname(plaintextOutputPath)) {
+    // Ensure the target directory exists
+    await lstat(path.dirname(plaintextOutputPath)).catch(async () => {
+      await mkdir(path.dirname(plaintextOutputPath), { recursive: true })
+    })
+
+    // Ensure correct extension is used
+    plaintextOutputPath = path.join(
+      path.dirname(plaintextOutputPath),
+      path.basename(plaintextOutputPath, path.extname(plaintextOutputPath)) + '.' + plaintextExtension
+    )
+
+    return writeFile(plaintextOutputPath, plaintext)
+  }
+
+  /**
+   * If `plaintextOutputPath` is a directory path, output file there, using the template's name
+   */
+  const templateFileName = get(templateConfig, 'build.current.path.name')
+
+  plaintextOutputPath = path.join(
+    plaintextOutputPath,
+    get(templateConfig, 'build.current.path.dir'),
+    templateFileName + '.' + plaintextExtension
+  )
+
+  // Ensure the target directory exists
+  await lstat(path.dirname(plaintextOutputPath)).catch(async () => {
+    await mkdir(path.dirname(plaintextOutputPath), { recursive: true })
+  })
+
+  return writeFile(plaintextOutputPath, plaintext)
+}

package/src/generators/render.js

@@ -0,0 +1,128 @@
+import { parse } from 'pathe'
+import posthtml from 'posthtml'
+import { cwd } from 'node:process'
+import { defu as merge } from 'defu'
+import expressions from 'posthtml-expressions'
+import { parseFrontMatter } from '../utils/node.js'
+import { process as compilePostHTML } from '../posthtml/index.js'
+import { run as useTransformers } from '../transformers/index.js'
+
+export async function render(html = '', config = {}) {
+  if (typeof html !== 'string') {
+    throw new TypeError(`first argument must be a string, received ${html}`)
+  }
+
+  if (html.length === 0) {
+    throw new RangeError('received empty string')
+  }
+
+  /**
+   * Parse front matter
+   *
+   * Parse expressions in front matter and add to config
+   * This could be handled by components() but plugins aren't working with it currently
+   */
+  let { content, matter } = parseFrontMatter(html)
+
+  /**
+    * Compute template config
+    *
+    * Merge it with front matter data and set the `cwd` for Tailwind.
+    */
+  const { data: matterData } = await posthtml(
+    [
+      expressions({
+        strictMode: false,
+        missingLocal: '{local}',
+        locals: {
+          page: config
+        }
+      })
+    ]
+  )
+    .process(matter)
+    .then(({ html }) => parseFrontMatter(`---${html}\n---`))
+
+  const templateConfig = merge(matterData, config)
+
+  /**
+   * Used for PostCSS `from` to make `@config` work in Tailwind
+   *
+   * @todo use only when in Node environment
+   */
+  templateConfig.cwd = parse(cwd()).base
+
+  /**
+   * Run `beforeRender` event
+   *
+   * @param {Object} options
+   * @param {string} options.html - The HTML to be transformed
+   * @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,
+      config: templateConfig,
+      render
+    })) ?? content
+  }
+
+  //  Compile PostHTML
+  const compiled = await compilePostHTML(content, templateConfig)
+
+  /**
+   * Run `afterRender` event
+   *
+   * @param {Object} options
+   * @param {string} options.html - The HTML to be transformed
+   * @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
+    })) ?? compiled.html
+  }
+
+  // Run Transformers
+  /**
+   * Run Transformers
+   *
+   * Runs only if `useTransformers` is not explicitly disabled in the config.
+   *
+   * @param {string} html - The HTML to be transformed
+   * @param {Object} config - The current template config
+   * @returns {string} - The transformed HTML
+   */
+  if (templateConfig.useTransformers !== false) {
+    compiled.html = await useTransformers(compiled.html, templateConfig).then(({ html }) => html)
+  }
+
+  // Run `afterTransformers` event
+  /**
+   * Run `afterTransformers` event
+   *
+   * @param {Object} options
+   * @param {string} options.html - The HTML to be transformed
+   * @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
+    })) ?? compiled.html
+  }
+
+  return {
+    config: templateConfig,
+    html: compiled.html,
+  }
+}

package/src/index.js

@@ -1,17 +1,49 @@
-const serve = require('./commands/serve')
-const toFile = require('./commands/build')
-const transformers = require('./transformers')
-const toString = require('./functions/render')
-const PostCSS = require('./generators/postcss')
-const toPlaintext = require('./functions/plaintext')
-const TailwindCSS = require('./generators/tailwindcss')
+import serve from './server/index.js'
+import build from './commands/build.js'
+import { render } from './generators/render.js'
 
-module.exports = {
+import { addAttributes } from './transformers/addAttributes.js'
+import { attributeToStyle } from './transformers/attributeToStyle.js'
+import { addBaseUrl } from './transformers/baseUrl.js'
+import { comb } from './transformers/comb.js'
+import { filters } from './transformers/filters/index.js'
+import { inline } from './transformers/inline.js'
+import { markdown } from './transformers/markdown.js'
+import { minify } from './transformers/minify.js'
+import { useMso } from './transformers/posthtmlMso.js'
+import { prettify } from './transformers/prettify.js'
+import { removeAttributes } from './transformers/removeAttributes.js'
+import { replaceStrings } from './transformers/replaceStrings.js'
+import { safeClassNames } from './transformers/safeClassNames.js'
+import { shorthandCSS } from './transformers/shorthandCss.js'
+import { sixHEX } from './transformers/sixHex.js'
+import { addURLParams } from './transformers/urlParameters.js'
+import { useAttributeSizes } from './transformers/useAttributeSizes.js'
+import { preventWidows } from './transformers/preventWidows.js'
+import { generatePlaintext } from './generators/plaintext.js'
+
+export {
+  build,
   serve,
-  build: toFile,
-  ...transformers,
-  render: toString,
-  postcss: PostCSS,
-  plaintext: toPlaintext,
-  tailwindcss: TailwindCSS
+  render,
+  addAttributes,
+  attributeToStyle,
+  addBaseUrl,
+  comb as removeUnusedCSS,
+  comb as purgeCSS,
+  filters,
+  inline as inlineCSS,
+  markdown,
+  minify,
+  useMso,
+  prettify,
+  removeAttributes,
+  replaceStrings,
+  safeClassNames,
+  shorthandCSS,
+  sixHEX,
+  addURLParams,
+  useAttributeSizes,
+  preventWidows,
+  generatePlaintext,
 }

package/src/{generators/posthtml → posthtml}/defaultComponentsConfig.js

@@ -1,9 +1,11 @@
-module.exports = {
+export default {
   root: './',
   folders: ['src/components', 'src/layouts', 'src/templates'],
   fileExtension: 'html',
   tag: 'component',
-  attribute: 'src',
-  yield: 'content',
-  propsAttribute: 'locals'
+  expressions: {
+    loopTags: ['each', 'for'],
+    missingLocal: '{local}',
+    strictMode: false,
+  },
 }

package/src/{generators/posthtml → posthtml}/defaultConfig.js

@@ -1,4 +1,4 @@
-module.exports = {
+export default {
   recognizeNoValueAttribute: true,
   recognizeSelfClosing: true
 }

package/src/posthtml/index.js

@@ -0,0 +1,74 @@
+import get from 'lodash-es/get.js'
+import { defu as merge } from 'defu'
+
+// PostHTML
+import posthtml from 'posthtml'
+import components from 'posthtml-component'
+import posthtmlPostcss from 'posthtml-postcss'
+import defaultPosthtmlConfig from './defaultConfig.js'
+import expandLinkTag from './plugins/expandLinkTag.js'
+
+// PostCSS
+import tailwindcss from 'tailwindcss'
+import postcssImport from 'postcss-import'
+import postcssSafeParser from 'postcss-safe-parser'
+import customProperties from 'postcss-custom-properties'
+
+import defaultComponentsConfig from './defaultComponentsConfig.js'
+
+export async function process(html = '', config = {}) {
+  const postcssPlugin = posthtmlPostcss(
+    [
+      postcssImport(),
+      tailwindcss(get(config, 'css.tailwind', {})),
+      get(config, 'css.inline.resolveCSSVariables', true) && customProperties(),
+      ...get(config, 'postcss.plugins', []),
+    ],
+    merge(
+      get(config, 'postcss.options', {}),
+      {
+        from: config.cwd || './',
+        parser: postcssSafeParser
+      }
+    )
+  )
+
+  const posthtmlOptions = merge(get(config, 'posthtml.options', {}), defaultPosthtmlConfig)
+
+  const componentsUserOptions = get(config, 'components', {})
+
+  const expressionsOptions = merge(
+    get(config, 'build.expressions', get(config, 'posthtml.expressions', {})),
+    get(componentsUserOptions, 'expressions', {}),
+  )
+
+  const locals = merge(
+    get(config, 'locals', {}),
+    get(expressionsOptions, 'locals', {}),
+    { page: config },
+  )
+
+  return posthtml([
+    ...get(config, 'posthtml.plugins.before', []),
+    expandLinkTag,
+    postcssPlugin,
+    components(
+      merge({
+        expressions: {
+          locals,
+        }
+      }, defaultComponentsConfig)
+    ),
+    expandLinkTag,
+    postcssPlugin,
+    ...get(config, 'posthtml.plugins.after', get(config, 'posthtml.plugins', []))
+  ])
+    .process(html, posthtmlOptions)
+    .then(result => ({
+      config,
+      html: result.html,
+    }))
+    .catch(error => {
+      throw error
+    })
+}

package/src/posthtml/plugins/expandLinkTag.js

@@ -0,0 +1,36 @@
+import fs from 'node:fs'
+
+const targets = new Set(['expand', 'inline'])
+
+// TODO: refactor to a Promise so we can use async readFile
+const plugin = (() => tree => {
+  const process = node => {
+    /**
+     * Don't expand link tags that are not explicitly marked as such
+     */
+    if (node.attrs && ![...targets].some(attr => attr in node.attrs)) {
+      for (const attr of targets) {
+        node.attrs[attr] = false
+      }
+
+      return node
+    }
+
+    if (
+      node.tag === 'link'
+      && node.attrs
+      && node.attrs.href
+      && node.attrs.rel === 'stylesheet'
+    ) {
+      node.content = [fs.readFileSync(node.attrs.href, 'utf8')]
+      node.tag = 'style'
+      node.attrs = {}
+    }
+
+    return node
+  }
+
+  return tree.walk(process)
+})()
+
+export default plugin