@maizzle/framework 6.0.0-0 → 6.0.0-2

package/CHANGELOG.md

@@ -4,6 +4,81 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.0.0-2] - 2025-07-11
+
+### Fixed
+
+- fixed an issue with duplicate CSS selectors for utilities that cannot be disabled in Tailwind CSS v4, like `text-decoration`
+- fixed an issue where some Tailwind directives like `@layer` or `@property` were still present in the final build, even though they were not used
+
+## [6.0.0-1] - 2025-07-11
+
+### Added
+
+- types for `css.combineMediaQueries` and `css.lightningcss` options in the config
+
+### Changed
+
+- made `combineMediaQueries` configurable through the `css.combineMediaQueries` option, which can be set to an object with options for `postcss-sort-media-queries` or to `false` to disable it
+- made `lightningcss` configurable through the `css.lightningcss` option
+
+### Fixed
+
+- fixed an issue with CSS syntax lowering, we now use `lightningcss` directly instead of `postcss-lightningcss` which was it to trip on CSS inside `style=""` attributes
+
+## [6.0.0-0] - 2025-07-10
+
+This release adds initial support for Tailwind CSS v4 in Maizzle.
+
+To jump right in, simply use the `next` branch of the Starter:
+
+```sh
+git clone -b next https://github.com/maizzle/maizzle.git
+```
+
+Or, if you have a project:
+
+1. Update `package.json`:
+
+  ```json
+  {
+    "private": true,
+    "type": "module",
+    "scripts": {
+      "dev": "maizzle serve",
+      "build": "maizzle build"
+    },
+    "dependencies": {
+      "@maizzle/framework": "next",
+      "@maizzle/tailwindcss": "latest"
+    }
+  }
+  ```
+
+2. Update the `style` tag in `layouts/main.html`:
+
+  ```html
+  <style>
+    @import "@maizzle/tailwindcss";
+
+    img {
+      @apply max-w-full align-middle;
+    }
+  </style>
+  ```
+
+There are still things missign and/or broken:
+
+- inline CSS like the `line-height` on spacers is broken/missing
+- `tailwindcss-email-variants` and `tailwindcss-mso` are not ported yet
+- some CSS duplication and artifacts still present in the final build
+
+---
+
+- feat: add tailwindcss v4 support  8b5596e
+
+https://github.com/maizzle/framework/compare/v5.2.1...v6.0.0-0
+
 ## [5.2.1] - 2025-06-25
 
 This is just a maintenance release to update dependencies.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maizzle/framework",
-  "version": "6.0.0-0",
+  "version": "6.0.0-2",
   "description": "Maizzle is a framework that helps you quickly build HTML emails with Tailwind CSS.",
   "license": "MIT",
   "type": "module",
@@ -65,6 +65,7 @@
     "is-url-superb": "^6.1.0",
     "istextorbinary": "^9.5.0",
     "juice": "^11.0.0",
+    "lightningcss": "^1.30.1",
     "lodash-es": "^4.17.21",
     "morphdom": "^2.7.4",
     "ora": "^8.1.0",
@@ -72,7 +73,6 @@
     "postcss": "^8.4.49",
     "postcss-calc": "^10.0.2",
     "postcss-css-variables": "^0.19.0",
-    "postcss-lightningcss": "^1.0.1",
     "postcss-safe-parser": "^7.0.0",
     "postcss-sort-media-queries": "^5.2.0",
     "posthtml": "^0.16.6",

package/src/posthtml/index.js

@@ -10,6 +10,7 @@ import posthtmlPostcss from 'posthtml-postcss'
 import expandLinkTag from './plugins/expandLinkTag.js'
 import envAttributes from './plugins/envAttributes.js'
 import { getPosthtmlOptions } from './defaultConfig.js'
+import lowerCssSyntax from './plugins/lowerCssSyntax.js'
 import combineMediaQueries from './plugins/combineMediaQueries.js'
 
 // PostCSS
@@ -17,7 +18,8 @@ import tailwindcss from '@tailwindcss/postcss'
 import postcssCalc from 'postcss-calc'
 import cssVariables from 'postcss-css-variables'
 import postcssSafeParser from 'postcss-safe-parser'
-import postcssLightningCss from 'postcss-lightningcss'
+import removeDuplicateSelectors from './plugins/postcss/removeDuplicateSelectors.js'
+import cleanupTailwindArtifacts from './plugins/postcss/cleanupTailwindArtifacts.js'
 
 import defaultComponentsConfig from './defaultComponentsConfig.js'
 
@@ -36,15 +38,8 @@ export async function process(html = '', config = {}) {
       tailwindcss(get(config, 'css.tailwind', {})),
       resolveCSSProps !== false && cssVariables(resolveCSSProps),
       resolveCalc !== false && postcssCalc(resolveCalc),
-      postcssLightningCss({
-        lightningcssOptions: {
-          errorRecovery: true,
-          minify: false,
-          targets: {
-            ie: 1,
-          }
-        }
-      }),
+      removeDuplicateSelectors(),
+      cleanupTailwindArtifacts(get(config, 'css.cleanup', {})),
       ...get(config, 'postcss.plugins', []),
     ],
     merge(
@@ -121,7 +116,8 @@ export async function process(html = '', config = {}) {
     postcssPlugin,
     envTags(config.env),
     envAttributes(config.env),
-    combineMediaQueries(get(config, 'css.combineMediaQueries', { sort: 'mobile-first' })),
+    lowerCssSyntax(get(config, 'css.lightningcss', {})),
+    get(config, 'css.combineMediaQueries') !== false && combineMediaQueries(get(config, 'css.combineMediaQueries', { sort: 'mobile-first' })),
     ...get(
       config,
       'posthtml.plugins.after',
@@ -129,7 +125,7 @@ export async function process(html = '', config = {}) {
         ? []
         : get(config, 'posthtml.plugins', [])
     ),
-  ])
+  ].filter(Boolean))
     .process(html, posthtmlOptions)
     .then(result => ({
       config: merge(config, { page: config }),

package/src/posthtml/plugins/lowerCssSyntax.js

@@ -0,0 +1,43 @@
+import { defu as merge } from 'defu'
+import { transform } from 'lightningcss'
+
+const plugin = (options = {}) => tree => {
+  options = merge(options, {
+    targets: options.targets ? {} : {
+      ie: 1,
+    },
+  })
+
+  const process = node => {
+    // Check if this is a style tag with content
+    if (node.tag === 'style' && node.content && Array.isArray(node.content)) {
+      // Get the CSS content from the style tag
+      const cssContent = node.content.join('')
+
+      if (cssContent.trim()) {
+        try {
+          const { code } = transform(
+            merge(
+              options,
+              {
+                code: Buffer.from(cssContent)
+              }
+            )
+          )
+
+          // Replace the content with processed CSS
+          node.content = [code.toString()]
+        } catch (error) {
+          // If processing fails, leave the content unchanged
+          console.warn('Failed to process media queries:', error.message)
+        }
+      }
+    }
+
+    return node
+  }
+
+  return tree.walk(process)
+}
+
+export default plugin

package/src/posthtml/plugins/postcss/cleanupTailwindArtifacts.js

@@ -0,0 +1,78 @@
+/**
+ * PostCSS plugin to clean up Tailwind CSS artifacts and leftovers.
+ *
+ * This plugin safely removes unused Tailwind-specific CSS that
+ * may be left behind after processing, while preserving
+ * any CSS that might be intentionally used.
+ */
+export default function cleanupTailwindArtifacts(options = {}) {
+  const opts = {
+    removeEmptyLayers: true,
+    removeUnusedTwProperties: true,
+    removeEmptyRules: false,
+    preserveCustomProperties: [], // Array of custom property names to preserve
+    ...options
+  }
+
+  return {
+    postcssPlugin: 'cleanup-tailwind-artifacts',
+    OnceExit(root) {
+      const usedCustomProperties = new Set()
+      const rulesToRemove = []
+
+      // First pass: collect all custom properties usage
+      root.walkDecls(decl => {
+        // Check if any declaration uses custom properties
+        if (decl.value.includes('var(--')) {
+          const matches = decl.value.match(/var\(--[\w-]+\)/g)
+          if (matches) {
+            matches.forEach(match => {
+              const propName = match.replace(/var\(|-|\)/g, '')
+              usedCustomProperties.add(propName)
+            })
+          }
+        }
+      })
+
+      // Second pass: find unused @property declarations and empty @layer rules
+      root.walkAtRules(rule => {
+        // Handle @property declarations
+        if (rule.name === 'property' && opts.removeUnusedTwProperties) {
+          const propertyName = rule.params.replace(/^--/, '')
+
+          // Only remove Tailwind-specific custom properties that aren't used
+          if (propertyName.startsWith('tw-') && !usedCustomProperties.has(propertyName)) {
+            // Check if it's in the preserve list
+            if (!opts.preserveCustomProperties.includes(propertyName)) {
+              rulesToRemove.push(rule)
+            }
+          }
+        }
+
+        // Handle @layer rules
+        if (rule.name === 'layer' && opts.removeEmptyLayers) {
+          // Only remove @layer rules that have no nodes
+          if (!rule.nodes || rule.nodes.length === 0) {
+            rulesToRemove.push(rule)
+          }
+        }
+      })
+
+      // Third pass: remove empty rules (optional, off by default)
+      if (opts.removeEmptyRules) {
+        root.walkRules(rule => {
+          if (!rule.nodes || rule.nodes.length === 0) {
+            rulesToRemove.push(rule)
+          }
+        })
+      }
+
+      // Remove all identified artifacts
+      rulesToRemove.forEach(rule => {
+        rule.remove()
+      })
+    }
+  }
+}
+
+cleanupTailwindArtifacts.postcss = true

package/src/posthtml/plugins/postcss/removeDuplicateSelectors.js

@@ -0,0 +1,35 @@
+/**
+ * PostCSS plugin to remove duplicate selectors, keeping only the last occurrence.
+ * This is useful when CSS contains multiple rules with the same selector,
+ * and we want to keep only the most recent one.
+ */
+export default function removeDuplicateSelectors() {
+  return {
+    postcssPlugin: 'remove-duplicate-selectors',
+    OnceExit(root) {
+      const selectorMap = new Map()
+      const rulesToRemove = []
+
+      // First pass: collect all rules and their selectors
+      root.walkRules(rule => {
+        const selector = rule.selector
+
+        // If we've seen this selector before, mark the previous one for removal
+        if (selectorMap.has(selector)) {
+          const previousRule = selectorMap.get(selector)
+          rulesToRemove.push(previousRule)
+        }
+
+        // Update the map with the current rule (latest occurrence)
+        selectorMap.set(selector, rule)
+      })
+
+      // Second pass: remove all the duplicate rules
+      rulesToRemove.forEach(rule => {
+        rule.remove()
+      })
+    }
+  }
+}
+
+removeDuplicateSelectors.postcss = true

package/src/transformers/inline.js

@@ -177,69 +177,71 @@ export async function inline(html = '', options = {}) {
 
     // Loop over selectors that we found in the <style> tags
     selectors.forEach(({ name, prop }) => {
-      const elements = $(name).get()
-
-      // If the property is excluded from inlining, skip
-      if (!juice.excludedProperties.includes(prop)) {
-        // Find the selector in the HTML
-        elements.forEach((el) => {
-          // Get a `property|value` list from the inline style attribute
-          const styleAttr = $(el).attr('style')
-          const inlineStyles = {}
-
-          // 1. `preferUnitlessValues`
-          if (styleAttr) {
-            try {
-              const root = postcss.parse(`* { ${styleAttr} }`)
-
-              root.first.each((decl) => {
-                const property = decl.prop
-                let value = decl.value
-
-                if (value && options.preferUnitlessValues) {
-                  value = value.replace(
-                    /\b0(px|rem|em|%|vh|vw|vmin|vmax|in|cm|mm|pt|pc|ex|ch)\b/g,
-                    '0'
-                  )
-                }
+      try {
+        const elements = $(name).get()
+
+        // If the property is excluded from inlining, skip
+        if (!juice.excludedProperties.includes(prop)) {
+          // Find the selector in the HTML
+          elements.forEach((el) => {
+            // Get a `property|value` list from the inline style attribute
+            const styleAttr = $(el).attr('style')
+            const inlineStyles = {}
+
+            // 1. `preferUnitlessValues`
+            if (styleAttr) {
+              try {
+                const root = postcss.parse(`* { ${styleAttr} }`)
+
+                root.first.each((decl) => {
+                  const property = decl.prop
+                  let value = decl.value
+
+                  if (value && options.preferUnitlessValues) {
+                    value = value.replace(
+                      /\b0(px|rem|em|%|vh|vw|vmin|vmax|in|cm|mm|pt|pc|ex|ch)\b/g,
+                      '0'
+                    )
+                  }
+
+                  if (property) {
+                    inlineStyles[property] = value
+                  }
+                })
+
+                // Update the element's style attribute with the new value
+                $(el).attr(
+                  'style',
+                  Object.entries(inlineStyles).map(([property, value]) => `${property}: ${value}`).join('; ')
+                )
+              } catch {}
+            }
+
+            // Get the classes from the element's class attribute
+            const classes = $(el).attr('class')
 
-                if (property) {
-                  inlineStyles[property] = value
+            // 2. `removeInlinedSelectors`
+            if (options.removeInlinedSelectors && classes) {
+              const classList = classes.split(' ')
+
+              // If the class has been inlined in the style attribute...
+              if (has(inlineStyles, prop)) {
+                // Try to remove the classes that have been inlined
+                if (![...options.safelist].some(item => item.includes(name))) {
+                  remove(classList, classToRemove => name.includes(classToRemove))
                 }
-              })
-
-              // Update the element's style attribute with the new value
-              $(el).attr(
-                'style',
-                Object.entries(inlineStyles).map(([property, value]) => `${property}: ${value}`).join('; ')
-              )
-            } catch {}
-          }
-
-          // Get the classes from the element's class attribute
-          const classes = $(el).attr('class')
-
-          // 2. `removeInlinedSelectors`
-          if (options.removeInlinedSelectors && classes) {
-            const classList = classes.split(' ')
-
-            // If the class has been inlined in the style attribute...
-            if (has(inlineStyles, prop)) {
-              // Try to remove the classes that have been inlined
-              if (![...options.safelist].some(item => item.includes(name))) {
-                remove(classList, classToRemove => name.includes(classToRemove))
-              }
 
-              // Update the class list on the element with the new classes
-              if (classList.length > 0) {
-                $(el).attr('class', classList.join(' '))
-              } else {
-                $(el).removeAttr('class')
+                // Update the class list on the element with the new classes
+                if (classList.length > 0) {
+                  $(el).attr('class', classList.join(' '))
+                } else {
+                  $(el).removeAttr('class')
+                }
               }
             }
-          }
-        })
-      }
+          })
+        }
+      } catch {}
     })
   })
 

package/types/config.d.ts

@@ -14,9 +14,10 @@ import type { BaseURLConfig } from 'posthtml-base-url';
 import type URLParametersConfig from './urlParameters';
 import type { PostCssCalcOptions } from 'postcss-calc';
 import type { PostHTMLFetchConfig } from 'posthtml-fetch';
-import type { Config as TailwindConfig } from 'tailwindcss';
 import type { PostHTMLComponents } from 'posthtml-component';
 import type { PostHTMLExpressions } from 'posthtml-expressions';
+import type { TransformOptions, CustomAtRules } from 'lightningcss';
+import type { PostCSSSortMediaQueriesOptions } from './css/combineMediaQueries';
 
 export default interface Config {
   /**
@@ -217,9 +218,30 @@ export default interface Config {
     sixHex?: boolean;
 
     /**
-     * Use a custom Tailwind CSS configuration object.
+     * Configure Lightning CSS.
+     *
+     * This is used mainly for lowering CSS syntax to be more compatible with email clients.
+     */
+    lightningcss?: TransformOptions<CustomAtRules>;
+
+    /**
+     * Combine media queries in your CSS.
+     *
+     * @default { sort: 'mobile-first' }
+     *
+     * @example
+     * ```
+     * export default {
+     *   css: {
+     *     combineMediaQueries: {
+     *       sort: 'desktop-first',
+     *       onlyTopLevel: true,
+     *     }
+     *   }
+     * }
+     * ```
      */
-    tailwind?: TailwindConfig;
+    combineMediaQueries?: PostCSSSortMediaQueriesOptions;
   }
 
   /**

package/types/css/combineMediaQueries.d.ts

@@ -0,0 +1,90 @@
+import type { Plugin } from 'postcss';
+
+/**
+ * Sort function for media queries.
+ * Takes two media query strings and returns a number indicating their relative order.
+ */
+export type SortFunction = (a: string, b: string) => number;
+
+/**
+ * Configuration object for sort-css-media-queries library.
+ */
+export interface SortConfiguration {
+  [key: string]: any;
+}
+
+/**
+ * Options for the postcss-sort-media-queries plugin.
+ */
+export interface PostCSSSortMediaQueriesOptions {
+  /**
+   * Sorting method for media queries.
+   *
+   * @default 'mobile-first'
+   *
+   * @example
+   * ```
+   * // Use built-in mobile-first sorting
+   * sort: 'mobile-first'
+   *
+   * // Use built-in desktop-first sorting
+   * sort: 'desktop-first'
+   *
+   * // Use custom sorting function
+   * sort: (a, b) => a.localeCompare(b)
+   * ```
+   */
+  sort?: 'mobile-first' | 'desktop-first' | SortFunction;
+
+  /**
+   * Custom configuration object for the sort-css-media-queries library.
+   * When provided, it will be used to create a custom sort function.
+   *
+   * @default false
+   *
+   * @example
+   * ```
+   * configuration: {
+   *   unitlessMqAlwaysFirst: true,
+   *   sort: 'mobile-first'
+   * }
+   * ```
+   */
+  configuration?: false | SortConfiguration;
+
+  /**
+   * Whether to only process media queries at the top level (direct children of root).
+   * When true, nested media queries will be ignored.
+   *
+   * @default false
+   *
+   * @example
+   * ```
+   * onlyTopLevel: true
+   * ```
+   */
+  onlyTopLevel?: boolean;
+}
+
+/**
+ * PostCSS plugin that sorts CSS media queries.
+ *
+ * @param options - Plugin configuration options
+ * @returns PostCSS plugin instance
+ *
+ * @example
+ * ```
+ * import postcss from 'postcss';
+ * import sortMediaQueries from 'postcss-sort-media-queries';
+ *
+ * postcss([
+ *   sortMediaQueries({
+ *     sort: 'mobile-first',
+ *     onlyTopLevel: false
+ *   })
+ * ])
+ * ```
+ */
+declare function postcssSortMediaQueries(options?: PostCSSSortMediaQueriesOptions): Plugin;
+
+export default postcssSortMediaQueries;