mjml-rb 0.2.32 → 0.2.34

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f70adefb32b3a7bb2df503b8749cfbd2fde06bb819c6bfc3e587a1a8eb65772
-  data.tar.gz: ef1c17cd44ec046c37c75b3a6650610161fe74f71824dfe64b72db2958e24f77
+  metadata.gz: bae58d9f87e82dc3c39bd0c9fca4949bb2a953cf8e22a2dd56fa2d5ff057a566
+  data.tar.gz: b892f3ed57cf49cf3935a60cd8abef4f232544b0bb2abf2999ef5a557b49849f
 SHA512:
-  metadata.gz: 64230656cfbf00b6d220cb579e078cddda30edeb5ccf1faa9f4245ed389ba76f6fe1990a10f48a6ccc2e67ecc3deb0c09cb6d4d146079d992e08cf5376f55c60
-  data.tar.gz: cb12486d8dd7571e11f19bbed0054a7698def27350678874c65c07688baf28a5b2e19f5bb31db4d4ce7c761e3509114c6d2b85155567a842e1812a1d82ba985b
+  metadata.gz: 320fa67da655fcb902557e784e8f1411ab94316b0c1d9e18b2890a6e25fba015ce159fe8ae6e404fbfa60273c9db3a0fdb45320abc9d72eba19a7eff8867706a
+  data.tar.gz: e6e3176e0c1cf87791bac2625ea520c339a4059f9ef474b74e16cc2ffd6bd8c1664caa35bd429e2c963d4f39167051fbaf7e391669d44cec93e7788664e5d519

data/lib/mjml-rb/ast_node.rb

@@ -1,13 +1,14 @@
 module MjmlRb
   class AstNode
-    attr_reader :tag_name, :attributes, :children, :content, :line
+    attr_reader :tag_name, :attributes, :children, :content, :line, :file
 
-    def initialize(tag_name:, attributes: {}, children: [], content: nil, line: nil)
+    def initialize(tag_name:, attributes: {}, children: [], content: nil, line: nil, file: nil)
       @tag_name = tag_name.to_s
       @attributes = attributes.transform_keys(&:to_s)
       @children = Array(children)
       @content = content
       @line = line
+      @file = file
     end
 
     def text?

data/lib/mjml-rb/components/text.rb

@@ -76,7 +76,7 @@ module MjmlRb
           "height" => height
         )
 
-        content = html_inner(node)
+        content = raw_inner(node)
         inner_div = %(<div style="#{div_style}">#{content}</div>)
 
         body = if height

data/lib/mjml-rb/parser.rb

@@ -8,6 +8,15 @@ module MjmlRb
     include REXML
     HTML_VOID_TAGS = %w[area base br col embed hr img input link meta param source track wbr].freeze
 
+    # Ending-tag components whose inner HTML is preserved as raw content via CDATA
+    # wrapping, matching upstream npm's endingTag behavior. mj-table is excluded
+    # because its component needs structural AST access for attribute normalization.
+    # mj-carousel-image is excluded because it has no meaningful inner content.
+    ENDING_TAGS_FOR_CDATA = %w[
+      mj-accordion-text mj-accordion-title mj-button
+      mj-navbar-link mj-raw mj-text
+    ].freeze
+
     class ParseError < StandardError
       attr_reader :line
 
@@ -20,11 +29,12 @@ module MjmlRb
     def parse(mjml, options = {})
       opts = normalize_options(options)
       xml = apply_preprocessors(mjml.to_s, opts[:preprocessors])
-      xml = wrap_raw_tags_in_cdata(xml)
+      xml = wrap_ending_tags_in_cdata(xml)
       xml = normalize_html_void_tags(xml)
       xml = expand_includes(xml, opts) unless opts[:ignore_includes]
 
-      doc = Document.new(sanitize_bare_ampersands(xml))
+      xml = annotate_line_numbers(sanitize_bare_ampersands(xml))
+      doc = Document.new(xml)
       element_to_ast(doc.root, keep_comments: opts[:keep_comments])
     rescue ParseException => e
       raise ParseError.new("XML parse error: #{e.message}")
@@ -48,45 +58,112 @@ module MjmlRb
       end
     end
 
-    def expand_includes(xml, options)
-      xml = wrap_raw_tags_in_cdata(xml)
+    def expand_includes(xml, options, included_in = [])
+      xml = wrap_ending_tags_in_cdata(xml)
       xml = normalize_html_void_tags(xml)
       doc = Document.new(sanitize_bare_ampersands(xml))
       includes = XPath.match(doc, "//mj-include")
       return xml if includes.empty?
 
+      css_includes = []
+
       includes.reverse_each do |include_node|
         path_attr = include_node.attributes["path"]
         raise ParseError, "mj-include path is required" if path_attr.to_s.empty?
 
         include_type = include_node.attributes["type"].to_s
-        resolved_path = resolve_include_path(path_attr, options[:actual_path], options[:file_path])
-        include_content = File.read(resolved_path)
+        parent = include_node.parent
+
+        resolved_path = begin
+          resolve_include_path(path_attr, options[:actual_path], options[:file_path])
+        rescue Errno::ENOENT
+          nil
+        end
+
+        include_content = resolved_path ? File.read(resolved_path) : nil
+
+        if include_content.nil?
+          # Collect error as an mj-raw comment node instead of raising
+          display_path = resolved_path || File.expand_path(path_attr, options[:file_path].to_s)
+          error_comment = "<!-- mj-include fails to read file : #{path_attr} at #{display_path} -->"
+          error_node = Element.new("mj-raw")
+          error_node.add(CData.new(error_comment))
+          parent.insert_before(include_node, error_node)
+          parent.delete(include_node)
+          next
+        end
+
+        # Circular include detection
+        if included_in.include?(resolved_path)
+          raise ParseError, "Circular inclusion detected on file : #{resolved_path}"
+        end
+
+        if include_type == "css"
+          # CSS includes get collected and added to mj-head later
+          css_inline = include_node.attributes["css-inline"].to_s
+          css_includes << { content: include_content, inline: css_inline == "inline" }
+          parent.delete(include_node)
+          next
+        end
 
         replacement = if include_type == "html"
                         %(<mj-raw><![CDATA[#{escape_cdata(include_content)}]]></mj-raw>)
                       else
-                        wrap_raw_tags_in_cdata(normalize_html_void_tags(strip_xml_declaration(include_content)))
+                        prepared = wrap_ending_tags_in_cdata(normalize_html_void_tags(strip_xml_declaration(include_content)))
+                        # Recursively expand includes in the included content
+                        expand_includes(prepared, options.merge(
+                          actual_path: resolved_path,
+                          file_path: File.dirname(resolved_path)
+                        ), included_in + [resolved_path])
                       end
 
         fragment = Document.new(sanitize_bare_ampersands("<include-root>#{replacement}</include-root>"))
-        parent = include_node.parent
         insert_before = include_node
         fragment.root.children.each do |child|
+          annotate_include_source(child, resolved_path) if child.is_a?(Element)
           parent.insert_before(insert_before, deep_clone(child))
         end
         parent.delete(include_node)
       end
 
+      # Inject CSS includes into mj-head
+      unless css_includes.empty?
+        inject_css_includes(doc, css_includes)
+      end
+
       output = +""
       doc.write(output)
       output
-    rescue Errno::ENOENT => e
-      raise ParseError, "Cannot read included file: #{e.message}"
     rescue ParseException => e
       raise ParseError, "Failed to parse included content: #{e.message}"
     end
 
+    def inject_css_includes(doc, css_includes)
+      mjml_root = doc.root
+      return unless mjml_root
+
+      # Find or create mj-head
+      head = XPath.first(mjml_root, "mj-head")
+      unless head
+        head = Element.new("mj-head")
+        # Insert mj-head before mj-body if possible
+        body = XPath.first(mjml_root, "mj-body")
+        if body
+          mjml_root.insert_before(body, head)
+        else
+          mjml_root.add(head)
+        end
+      end
+
+      # Add each CSS include as an mj-style element
+      css_includes.each do |css_include|
+        style_node = Element.new("mj-style")
+        style_node.add_attribute("inline", "inline") if css_include[:inline]
+        style_node.add(CData.new(css_include[:content]))
+        head.add(style_node)
+      end
+    end
+
     def strip_xml_declaration(content)
       content.sub(/\A<\?xml[^>]*\?>\s*/m, "")
     end
@@ -107,14 +184,20 @@ module MjmlRb
       end
     end
 
-    def wrap_raw_tags_in_cdata(content)
-      content.gsub(/<mj-raw(\s[^<>]*?)?>(.*?)<\/mj-raw>/mi) do
-        attrs = Regexp.last_match(1).to_s
-        inner = Regexp.last_match(2).to_s
+    def wrap_ending_tags_in_cdata(content)
+      tag_pattern = ENDING_TAGS_FOR_CDATA.map { |t| Regexp.escape(t) }.join("|")
+      # Negative lookbehind (?<!\/) ensures self-closing tags like <mj-text ... /> are skipped
+      content.gsub(/<(#{tag_pattern})(\s[^<>]*?)?(?<!\/)>(.*?)<\/\1>/mi) do
+        tag = Regexp.last_match(1)
+        attrs = Regexp.last_match(2).to_s
+        inner = Regexp.last_match(3).to_s
         if inner.include?("<![CDATA[")
-          "<mj-raw#{attrs}>#{inner}</mj-raw>"
+          "<#{tag}#{attrs}>#{inner}</#{tag}>"
         else
-          "<mj-raw#{attrs}><![CDATA[#{escape_cdata(inner)}]]></mj-raw>"
+          # Pre-process content: normalize void tags and sanitize bare ampersands
+          # before wrapping in CDATA, so the raw HTML is well-formed for output.
+          prepared = sanitize_bare_ampersands(normalize_html_void_tags(inner))
+          "<#{tag}#{attrs}><![CDATA[#{escape_cdata(prepared)}]]></#{tag}>"
         end
       end
     end
@@ -130,6 +213,36 @@ module MjmlRb
       content.gsub(/&(?!(?:#[0-9]+|#x[0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);)/, "&amp;")
     end
 
+    # Adds data-mjml-line attributes to MJML tags so line numbers survive
+    # REXML parsing (which doesn't expose source positions).
+    # Skips content inside CDATA sections to avoid modifying raw HTML.
+    def annotate_line_numbers(xml)
+      line = 1
+      xml.gsub(/(\n)|(<!\[CDATA\[.*?\]\]>)|(<(?:mj-[\w-]+|mjml)(?=[\s\/>]))/m) do
+        if Regexp.last_match(1) # newline
+          line += 1
+          "\n"
+        elsif Regexp.last_match(2) # CDATA section — count newlines, pass through
+          line += Regexp.last_match(2).count("\n")
+          Regexp.last_match(2)
+        else # opening MJML tag
+          "#{Regexp.last_match(3)} data-mjml-line=\"#{line}\""
+        end
+      end
+    end
+
+    # Recursively marks REXML elements from included files with data-mjml-file.
+    # Only sets the attribute on elements that don't already have it (preserving
+    # deeper include annotations from recursive expansion).
+    def annotate_include_source(element, file_path)
+      return unless element.is_a?(Element)
+
+      if (element.name.start_with?("mj-") || element.name == "mjml") && !element.attributes["data-mjml-file"]
+        element.add_attribute("data-mjml-file", file_path)
+      end
+      element.each_element { |child| annotate_include_source(child, file_path) }
+    end
+
     def resolve_include_path(include_path, actual_path, file_path)
       include_path = include_path.to_s
       return include_path if File.absolute_path(include_path) == include_path && File.file?(include_path)
@@ -164,6 +277,28 @@ module MjmlRb
     def element_to_ast(element, keep_comments:)
       raise ParseError, "Missing XML root element" unless element
 
+      # Extract metadata annotations (added by annotate_line_numbers / annotate_include_source)
+      # and strip them from the public attributes hash.
+      meta_line = element.attributes["data-mjml-line"]&.to_i
+      meta_file = element.attributes["data-mjml-file"]
+      attrs = element.attributes.each_with_object({}) do |(name, val), h|
+        h[name] = val unless name.start_with?("data-mjml-")
+      end
+
+      # For ending-tag elements whose content was wrapped in CDATA, store
+      # the raw HTML directly as content instead of parsing structurally.
+      if ENDING_TAGS_FOR_CDATA.include?(element.name)
+        raw_content = element.children.select { |c| c.is_a?(Text) }.map(&:value).join
+        return AstNode.new(
+          tag_name: element.name,
+          attributes: attrs,
+          children: [],
+          content: raw_content.empty? ? nil : raw_content,
+          line: meta_line,
+          file: meta_file
+        )
+      end
+
       children = element.children.each_with_object([]) do |child, memo|
         case child
         when Element
@@ -178,9 +313,10 @@ module MjmlRb
 
       AstNode.new(
         tag_name: element.name,
-        attributes: element.attributes.each_with_object({}) { |(name, val), h| h[name] = val },
+        attributes: attrs,
         children: children,
-        line: nil
+        line: meta_line,
+        file: meta_file
       )
     end
   end

data/lib/mjml-rb/renderer.rb

@@ -296,7 +296,9 @@ module MjmlRb
       return html if css_blocks.empty?
 
       document = parse_html_document(html)
-      parse_inline_css_rules(css_blocks.join("\n")).each do |selector, declarations|
+      rules, at_rules_css = parse_inline_css_rules(css_blocks.join("\n"))
+
+      rules.each do |selector, declarations|
         next if selector.empty? || declarations.empty?
 
         select_nodes(document, selector).each do |node|
@@ -304,6 +306,11 @@ module MjmlRb
         end
       end
 
+      # Inject preserved @-rules (@media, @font-face, etc.) as a <style> block.
+      # These rules cannot be inlined into style attributes but should be kept
+      # in the document for runtime application by email clients.
+      inject_preserved_at_rules(document, at_rules_css)
+
       document.to_html
     end
 
@@ -315,6 +322,18 @@ module MjmlRb
       end
     end
 
+    def inject_preserved_at_rules(document, at_rules_css)
+      return if at_rules_css.nil? || at_rules_css.strip.empty?
+
+      head = document.at_css("head")
+      return unless head
+
+      style = Nokogiri::XML::Node.new("style", document)
+      style["type"] = "text/css"
+      style.content = at_rules_css.strip
+      head.add_child(style)
+    end
+
     def select_nodes(document, selector)
       document.css(selector)
     rescue Nokogiri::CSS::SyntaxError, Nokogiri::XML::XPath::SyntaxError
@@ -356,21 +375,34 @@ module MjmlRb
 
     def parse_inline_css_rules(css)
       stripped_css = strip_css_comments(css.to_s)
-      plain_css = strip_css_at_rules(stripped_css)
+      plain_css, at_rules_css = extract_css_at_rules(stripped_css)
 
-      plain_css.scan(/([^{}]+)\{([^{}]+)\}/m).flat_map do |selector_group, declarations|
+      rules = plain_css.scan(/([^{}]+)\{([^{}]+)\}/m).flat_map do |selector_group, declarations|
         selectors = selector_group.split(",").map(&:strip).reject(&:empty?)
         declaration_map = parse_css_declarations(declarations)
         selectors.map { |selector| [selector, declaration_map] }
       end
+
+      # Sort rules by specificity (ascending). With the "last wins" merge
+      # strategy, higher-specificity rules applied later correctly override
+      # lower-specificity ones — matching CSS cascade behavior.
+      sorted = rules.each_with_index
+                    .sort_by { |(selector, _), idx| [css_specificity(selector), idx] }
+                    .map(&:first)
+
+      [sorted, at_rules_css]
     end
 
     def strip_css_comments(css)
       css.gsub(%r{/\*.*?\*/}m, "")
     end
 
-    def strip_css_at_rules(css)
-      result = +""
+    # Separates @-rules (@media, @font-face, etc.) from plain CSS selectors.
+    # Returns [plain_css, at_rules_css]. The at_rules_css can be injected as a
+    # <style> block since @-rules cannot be inlined into style attributes.
+    def extract_css_at_rules(css)
+      plain = +""
+      at_rules = +""
       index = 0
 
       while index < css.length
@@ -378,11 +410,14 @@ module MjmlRb
           brace_index = css.index("{", index)
           semicolon_index = css.index(";", index)
 
+          # Simple @-rules like @import or @charset end with semicolon
           if semicolon_index && (brace_index.nil? || semicolon_index < brace_index)
+            at_rules << css[index..semicolon_index] << "\n"
             index = semicolon_index + 1
             next
           end
 
+          # Block @-rules like @media, @font-face have nested braces
           if brace_index
             depth = 1
             cursor = brace_index + 1
@@ -391,16 +426,49 @@ module MjmlRb
               depth -= 1 if css[cursor] == "}"
               cursor += 1
             end
+            at_rules << css[index...cursor] << "\n"
             index = cursor
             next
           end
         end
 
-        result << css[index]
+        plain << css[index]
         index += 1
       end
 
-      result
+      [plain, at_rules]
+    end
+
+    # Calculates CSS specificity as a comparable [a, b, c] tuple:
+    #   a = number of ID selectors (#id)
+    #   b = number of class selectors (.class), attribute selectors ([attr]),
+    #       and pseudo-classes (:hover, :lang())
+    #   c = number of type selectors (div, p) and pseudo-elements (::before)
+    def css_specificity(selector)
+      s = selector.to_s
+
+      # a: ID selectors
+      a = s.scan(/#[\w-]+/).length
+
+      # b: class selectors + attribute selectors + pseudo-classes
+      b = s.scan(/\.[\w-]+/).length +
+          s.scan(/\[[^\]]*\]/).length +
+          s.scan(/:(?!:)[\w-]+/).length
+
+      # c: type selectors + pseudo-elements
+      # Strip everything except element names and combinators
+      cleaned = s
+        .gsub(/#[\w-]+/, "")                           # remove IDs
+        .gsub(/\.[\w-]+/, "")                           # remove classes
+        .gsub(/\[[^\]]*\]/, "")                         # remove attribute selectors
+        .gsub(/:[\w-]+(?:\([^)]*\))?/, "")              # remove pseudo-classes
+        .gsub(/::[\w-]+/, "")                           # remove pseudo-elements (counted separately)
+        .gsub(/[>+~]/, " ")                             # combinators → spaces
+        .gsub(/\*/, "")                                 # universal selector has no specificity
+      c = cleaned.split.reject(&:empty?).length +
+          s.scan(/::[\w-]+/).length
+
+      [a, b, c]
     end
 
     def parse_css_declarations(declarations)
@@ -580,6 +648,9 @@ module MjmlRb
     end
 
     def raw_inner(node)
+      # For ending-tag nodes whose content was preserved as raw HTML by the parser
+      return node.content if node.element? && node.content
+
       if node.respond_to?(:children)
         node.children.map do |child|
           if child.text?

data/lib/mjml-rb/validator.rb

@@ -64,7 +64,7 @@ module MjmlRb
 
         errors << error(
           "Element <#{child.tag_name}> is not allowed inside <#{node.tag_name}>",
-          tag_name: child.tag_name
+          tag_name: child.tag_name, line: child.line, file: child.file
         )
       end
     end
@@ -74,7 +74,8 @@ module MjmlRb
       required.each do |attr|
         next if node.attributes.key?(attr)
 
-        errors << error("Attribute `#{attr}` is required for <#{node.tag_name}>", tag_name: node.tag_name)
+        errors << error("Attribute `#{attr}` is required for <#{node.tag_name}>",
+                        tag_name: node.tag_name, line: node.line, file: node.file)
       end
     end
 
@@ -86,7 +87,8 @@ module MjmlRb
         next if allowed_attributes.key?(attribute_name)
         next if GLOBAL_ALLOWED_ATTRIBUTES.include?(attribute_name)
 
-        errors << error("Attribute `#{attribute_name}` is not allowed for <#{node.tag_name}>", tag_name: node.tag_name)
+        errors << error("Attribute `#{attribute_name}` is not allowed for <#{node.tag_name}>",
+                        tag_name: node.tag_name, line: node.line, file: node.file)
       end
     end
 
@@ -103,7 +105,7 @@ module MjmlRb
 
         errors << error(
           "Attribute `#{attribute_name}` on <#{node.tag_name}> has invalid value `#{attribute_value}` for type `#{expected_type}`",
-          tag_name: node.tag_name
+          tag_name: node.tag_name, line: node.line, file: node.file
         )
       end
     end
@@ -183,12 +185,18 @@ module MjmlRb
       end
     end
 
-    def error(message, line: nil, tag_name: nil)
+    def error(message, line: nil, tag_name: nil, file: nil)
+      location = [
+        ("line #{line}" if line),
+        ("in #{file}" if file)
+      ].compact.join(", ")
+
       {
         line: line,
+        file: file,
         message: message,
         tag_name: tag_name,
-        formatted_message: message
+        formatted_message: location.empty? ? message : "#{message} (#{location})"
       }
     end
   end

data/lib/mjml-rb/version.rb

@@ -1,3 +1,3 @@
 module MjmlRb
-  VERSION = "0.2.32".freeze
+  VERSION = "0.2.34".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mjml-rb
 version: !ruby/object:Gem::Version
-  version: 0.2.32
+  version: 0.2.34
 platform: ruby
 authors:
 - Andrei Andriichuk