mjml-rb 0.4.2 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0062fce070623c7a358e1af4811bb928a46d7f0cd4e1320a71e16276ccca1d74
-  data.tar.gz: a4e81e450419963570486009b46f44962d93c25b41cdbe4df721346db6e79fc8
+  metadata.gz: 750fc042cf9ff6273cebd5907a096e6fc304d28a49b0872cf6eec93f9818e148
+  data.tar.gz: 138a44a38b430267f646cd771b4a9fa01e3c0e9609083291de5270280db36650
 SHA512:
-  metadata.gz: 880bfd1a06dfe3fb9e8fe2169fe660554cb4e9ca96ee5d6eff1d2b41f6df748af14b753895d7b58a3106e33335516f6f4caadd2fd01717c597846b6104330fbf
-  data.tar.gz: 94f84fa6a66210d9177db704c16efa6fce09d983eb138bc5d13fdbf9bf967ac553b867907cfce9190a2bd7e14a6e6108c4ff74eb776d16221cbf77689f59ea85
+  metadata.gz: 5d83da073643a75183303c6a14a6b0cbd2e06d864875c80a4bbfc65ef5c857b5a4ffb2971a0465cc58e46b400efe8a1d760994f643a420da0d549837799f8bf5
+  data.tar.gz: 1bd7d0c899cb6de244ab534d0b598b12f437c53ef556cb7fd5c56880ec4d6fc164dedb493ad49e45e60b52e5bd9180dd725b7f91790eb2952440df5d5219bb3a

data/README.md

@@ -11,198 +11,98 @@
 > This is a **fully open source project** — feedback, bug reports, test cases,
 > and pull requests are welcome!
 
-This gem provides a Ruby-first implementation of the main MJML tooling:
+A pure-Ruby MJML v4 compiler — no Node.js required.
 
-- library API compatible with `mjml2html`
-- command-line interface (`mjml`)
-- validation commands
-- pure Ruby parser, AST, validator, and renderer
-- no Node.js runtime and no shelling out to the official npm renderer
+- Library API compatible with `mjml2html`
+- Command-line interface (`mjml`)
+- Rails integration (ActionView template handler for `.mjml` views)
+- Validation (soft, strict, skip)
+- Custom component support
+- Pure Ruby parser, AST, validator, and renderer
 
-Remaining parity work is tracked in [npm ↔ Ruby Parity Audit](docs/PARITY_AUDIT.md).
-
-## Compatibility
-
-This project targets **MJML v4 only**.
+**[Full Usage Guide](docs/USAGE.md)** — API reference, all compiler options, component attribute tables, CLI flags, Rails setup, custom components, and more.
 
-- parsing, validation, and rendering are implemented against the MJML v4 document structure
-- component rules and attribute validation follow the MJML v4 model
+## Installation
 
-## Quick start
-
-```bash
-bundle install
-bundle exec ruby -Ilib -e 'require "mjml-rb"; puts MjmlRb.mjml2html("<mjml><mj-body><mj-section><mj-column><mj-text>Hello</mj-text></mj-column></mj-section></mj-body></mjml>")[:html]'
+```ruby
+# Gemfile
+gem "mjml-rb"
 ```
 
-## CLI usage
+## Quick Start
 
-```bash
-bundle exec bin/mjml example.mjml -o output.html
-bundle exec bin/mjml --validate example.mjml
+```ruby
+require "mjml-rb"
+
+result = MjmlRb.mjml2html(<<~MJML)
+  <mjml>
+    <mj-body>
+      <mj-section>
+        <mj-column>
+          <mj-text>Hello World!</mj-text>
+        </mj-column>
+      </mj-section>
+    </mj-body>
+  </mjml>
+MJML
+
+puts result[:html]     # compiled HTML
+puts result[:errors]   # validation errors (if any)
 ```
 
-## Rails integration
-
-In a Rails app, requiring the gem registers an `ActionView` template handler for
-`.mjml` templates through a `Railtie`.
-
-By default, `.mjml` files are treated as raw MJML/XML source.
+## CLI
 
-If you want Slim-backed MJML templates, configure it explicitly:
-
-```ruby
-config.mjml_rb.rails_template_language = :slim
+```bash
+mjml email.mjml -o email.html          # compile to file
+mjml -r "templates/*.mjml" -o output/  # batch compile
+mjml -v email.mjml                     # validate only
+mjml -i -s < email.mjml                # stdin → stdout
 ```
 
-Supported values are `:slim` and `:haml`.
+See the [Usage Guide — CLI section](docs/USAGE.md#cli) for all flags and config options.
 
-With a configured `rails_template_language`, `.mjml` templates are rendered
-through that template engine first, so partials and embedded Ruby can assemble
-MJML before the outer template is compiled to HTML. Without that setting,
-non-XML MJML source is rejected instead of being guessed.
+## Rails
 
-For `:slim` or `:haml`, the matching Rails template handler must already be
-registered in `ActionView` by the corresponding gem or integration layer.
+Add the gem to your Gemfile — that's it. The `.mjml` template handler is registered automatically.
 
-Create a view such as `app/views/user_mailer/welcome.html.mjml`:
-
-```mjml
+```erb
+<!-- app/views/user_mailer/welcome.html.mjml -->
 <mjml>
   <mj-body>
     <mj-section>
       <mj-column>
-        <mj-text>Hello from Rails</mj-text>
+        <mj-text>Welcome, <%= @user.name %>!</mj-text>
       </mj-column>
     </mj-section>
   </mj-body>
 </mjml>
 ```
 
-Then render it like any other Rails template:
-
 ```ruby
 class UserMailer < ApplicationMailer
-  def welcome
-    mail(to: "user@example.com", subject: "Welcome")
+  def welcome(user)
+    @user = user
+    mail(to: user.email, subject: "Welcome")
   end
 end
 ```
 
-Rails rendering uses strict MJML validation by default. You can override the
-compiler options in your application config:
-
-```ruby
-config.mjml_rb.compiler_options = { validation_level: "soft" }
-```
-
-## Custom components
+Supports Slim and Haml via `config.mjml_rb.rails_template_language = :slim`. See the [Usage Guide — Rails section](docs/USAGE.md#rails-integration) for full configuration.
 
-You can register custom MJML components written in Ruby:
-
-```ruby
-class MjRating < MjmlRb::Components::Base
-  TAGS = ["mj-rating"].freeze
-  ALLOWED_ATTRIBUTES = { "stars" => "integer", "color" => "color" }.freeze
-  DEFAULT_ATTRIBUTES = { "stars" => "5", "color" => "#f4b400" }.freeze
-
-  def render(tag_name:, node:, context:, attrs:, parent:)
-    stars = (attrs["stars"] || "5").to_i
-    color = attrs["color"] || "#f4b400"
-    %(<div style="color:#{escape_attr(color)}">#{"\u2605" * stars}</div>)
-  end
-end
-
-MjmlRb.register_component(MjRating,
-  dependencies: { "mj-column" => ["mj-rating"] },
-  ending_tags: ["mj-rating"]
-)
-```
-
-The `dependencies` hash declares which parent tags accept the new component as a child. The `ending_tags` list tells the parser to treat content as raw HTML (like `mj-text`). Both are optional.
-
-Once registered, the component works in MJML markup and is validated like any built-in component.
-
-## `.mjmlrc` config file
-
-Place a `.mjmlrc` file (JSON) in your project root to auto-register custom components and set default compiler options:
+## Architecture
 
-```json
-{
-  "packages": [
-    "./lib/mjml_components/mj_rating.rb"
-  ],
-  "options": {
-    "beautify": true,
-    "validation-level": "soft"
-  }
-}
 ```
-
-- **`packages`** — Ruby files to `require`. Each file should call `MjmlRb.register_component` to register its components.
-- **`options`** — Default compiler options. CLI flags and programmatic options override these.
-
-The CLI loads `.mjmlrc` automatically from the working directory. For the library API, load it explicitly:
-
-```ruby
-MjmlRb::ConfigFile.load("/path/to/project")
-result = MjmlRb.mjml2html(mjml_string)
+MJML string → Parser → AST → Validator → Renderer → HTML
 ```
 
-## Architecture
+1. **Parser** — normalizes source, expands `mj-include`, builds `AstNode` tree
+2. **Validator** — checks structure, hierarchy, and attribute types
+3. **Renderer** — resolves head metadata, applies defaults, emits responsive HTML
 
-The compile pipeline is intentionally simple and fully Ruby-based:
-
-1. `MjmlRb.mjml2html` calls `MjmlRb::Compiler`.
-2. `MjmlRb::Parser` normalizes the source, expands `mj-include`, and builds an `AstNode` tree.
-3. `MjmlRb::Validator` checks structural rules and supported attributes.
-4. `MjmlRb::Renderer` resolves head metadata, applies component defaults, and renders HTML.
-5. `MjmlRb::Compiler` post-processes the output and returns a `Result`.
-
-The key architectural idea is that the project uses a small shared AST plus a component registry:
-
-- the parser produces generic `AstNode` objects instead of component-specific node types
-- structure rules live in `lib/mjml-rb/dependencies.rb`
-- rendering logic lives in `lib/mjml-rb/components/*`
-- head components populate a shared rendering context
-- body components consume that context and emit the final HTML
-
-That split keeps the compiler pipeline predictable:
-
-- parsing is responsible for source normalization and include expansion
-- validation is responsible for MJML structure and attribute checks
-- rendering is responsible for HTML generation and responsive email output
-
-## Project structure
-
-The main files are organized like this:
-
-```text
-lib/mjml-rb.rb                    # public gem entry point
-lib/mjml-rb/compiler.rb           # orchestration: parse -> validate -> render
-lib/mjml-rb/parser.rb             # MJML/XML normalization, includes, AST building
-lib/mjml-rb/ast_node.rb           # shared tree representation
-lib/mjml-rb/validator.rb          # structural and attribute validation
-lib/mjml-rb/dependencies.rb       # allowed parent/child relationships
-lib/mjml-rb/renderer.rb           # HTML document assembly and render context
-lib/mjml-rb/components/*          # per-component rendering and head handling
-lib/mjml-rb/result.rb             # result object returned by the compiler
-lib/mjml-rb/cli.rb                # CLI implementation used by bin/mjml
-docs/ARCHITECTURE.md              # deeper architecture notes
-docs/PARITY_AUDIT.md              # npm vs Ruby parity tracking
-```
+For the full internal walkthrough, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
-If you want the full internal walkthrough, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+Remaining parity work is tracked in [npm ↔ Ruby Parity Audit](docs/PARITY_AUDIT.md).
 
-## Implementation goal
+## License
 
-> **Ruby MJML pipeline without the Node.js renderer.**
->
-> The npm `mjml` package requires Node.js at build time (or runtime via a child
-> process / FFI bridge). This project replaces that entire pipeline with a single
-> Ruby library: XML parsing, AST construction, attribute resolution, validation,
-> and HTML rendering — all in Ruby, with no Node.js runtime and no need to
-> shell out to the official MJML renderer. Drop it into a Rails, Sinatra, or
-> plain Ruby project and render MJML templates the same way you render ERB — no
-> extra runtime, no
-> `package.json`, no `node_modules`.
+MIT

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

@@ -173,7 +173,7 @@ module MjmlRb
             when "mj-accordion-element"
               render_accordion_element(child, context, accordion_attrs)
             when "mj-raw"
-              raw_inner(child)
+              raw_inner_for_body(child)
             else
               render_node(child, context, parent: "mj-accordion")
             end
@@ -210,7 +210,7 @@ module MjmlRb
               child_attrs = attrs.merge(resolved_attributes(child, context))
               content << render_accordion_text(child, child_attrs)
             when "mj-raw"
-              content << raw_inner(child)
+              content << raw_inner_for_body(child)
             end
           end
         end
@@ -249,7 +249,7 @@ module MjmlRb
           "width" => "100%",
           "border-bottom" => title_attrs["border"] || DEFAULTS["border"]
         )
-        title_content = node ? raw_inner(node) : ""
+        title_content = node ? raw_inner_for_body(node) : ""
         title_cell = %(<td style="#{td_style}">#{title_content}</td>)
         icon_cell = %(<td class="mj-accordion-ico" style="#{td2_style}"><img src="#{escape_attr(title_attrs["icon-wrapped-url"] || DEFAULTS["icon-wrapped-url"])}" alt="#{escape_attr(title_attrs["icon-wrapped-alt"] || DEFAULTS["icon-wrapped-alt"])}" class="mj-accordion-more" style="#{icon_style}" /><img src="#{escape_attr(title_attrs["icon-unwrapped-url"] || DEFAULTS["icon-unwrapped-url"])}" alt="#{escape_attr(title_attrs["icon-unwrapped-alt"] || DEFAULTS["icon-unwrapped-alt"])}" class="mj-accordion-less" style="#{icon_style}" /></td>)
         cells = title_attrs["icon-position"] == "left" ? "#{icon_cell}#{title_cell}" : "#{title_cell}#{icon_cell}"
@@ -277,7 +277,7 @@ module MjmlRb
           "width" => "100%",
           "border-bottom" => text_attrs["border"] || DEFAULTS["border"]
         )
-        content = node ? raw_inner(node) : ""
+        content = node ? raw_inner_for_body(node) : ""
         css_class = text_attrs["css-class"] ? %( class="#{escape_attr(text_attrs["css-class"])}") : ""
 
         %(<div class="mj-accordion-content"><table role="presentation" width="100%" cellspacing="0" cellpadding="0" style="#{table_style}"><tbody><tr><td#{css_class} style="#{td_style}">#{content}</td></tr></tbody></table></div>)

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

@@ -50,6 +50,10 @@ module MjmlRb
         renderer.send(:raw_inner, node)
       end
 
+      def raw_inner_for_body(node)
+        renderer.send(:annotate_raw_html, raw_inner(node))
+      end
+
       # Like raw_inner but HTML-escapes text nodes. Use for components such as
       # mj-text where the inner content is treated as HTML but bare text must
       # be properly encoded (e.g. & -> &).

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

@@ -143,7 +143,7 @@ module MjmlRb
           link_attrs["title"] = a["title"]
         end
 
-        content = raw_inner(node)
+        content = raw_inner_for_body(node)
         inner_tag = %(<#{tag}#{html_attrs(link_attrs)}>#{content}</#{tag}>)
         table = %(<table border="0" cellpadding="0" cellspacing="0" role="presentation" style="#{table_style}"><tbody><tr><td#{html_attrs(td_attrs)}>#{inner_tag}</td></tr></tbody></table>)
 

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

@@ -205,7 +205,7 @@ module MjmlRb
           "style" => anchor_style
         }
 
-        content = raw_inner(node)
+        content = raw_inner_for_body(node)
         link = %(<a#{html_attrs(link_attrs)}>#{content}</a>)
         return link unless parent == "mj-navbar"
 

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

@@ -10,7 +10,7 @@ module MjmlRb
       }.freeze
 
       def render(tag_name:, node:, context:, attrs:, parent:)
-        raw_inner(node)
+        raw_inner_for_body(node)
       end
 
       def handle_head(node, context)

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

@@ -603,7 +603,7 @@ module MjmlRb
             "overflow"         => (has_border_radius ? "hidden" : nil),
             "margin"           => "0px auto",
             "margin-top"       => wrapper_gap,
-            "max-width"        => (full_width ? nil : "#{container_px}px")
+            "max-width"        => "#{container_px}px"
           }.merge(full_width ? {} : background_styles)
         )
 

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

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

data/lib/mjml-rb/parser.rb

@@ -18,13 +18,22 @@ module MjmlRb
     ].freeze
 
     # Pre-compiled regex patterns to avoid rebuilding on every call
-    ENDING_TAGS_CDATA_RE = /<(#{ENDING_TAGS_FOR_CDATA.map { |t| Regexp.escape(t) }.join("|")})(\s[^<>]*?)?(?<!\/)>(.*?)<\/\1>/mi.freeze
+    ENDING_TAG_OPEN_RE = /<(#{ENDING_TAGS_FOR_CDATA.map { |t| Regexp.escape(t) }.join("|")})(\s[^<>]*?)?(?<!\/)>/mi.freeze
 
     VOID_TAG_CLOSING_BR_RE = %r{</br\s*>}i.freeze
     VOID_TAG_CLOSING_OTHER_RE = /<\/(#{(HTML_VOID_TAGS - ["br"]).join("|")})\s*>/i.freeze
     VOID_TAG_OPEN_RE = /<(#{HTML_VOID_TAGS.join("|")})(\s[^<>]*?)?>/i.freeze
     LINE_ANNOTATION_RE = /(\n)|(<!\[CDATA\[.*?\]\]>)|(<(?:mj-[\w-]+|mjml)(?=[\s\/>]))/m.freeze
     BARE_AMPERSAND_RE = /&(?!(?:#[0-9]+|#x[0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);)/.freeze
+    ROOT_LEVEL_HEAD_TAGS = %w[
+      mj-attributes
+      mj-breakpoint
+      mj-html-attributes
+      mj-font
+      mj-preview
+      mj-style
+      mj-title
+    ].freeze
 
     class ParseError < StandardError
       attr_reader :line
@@ -49,6 +58,7 @@ module MjmlRb
 
       xml = annotate_line_numbers(sanitize_bare_ampersands(xml))
       doc = Document.new(xml)
+      normalize_root_head_elements(doc)
       element_to_ast(doc.root, keep_comments: opts[:keep_comments])
     rescue ParseException => e
       raise ParseError.new("XML parse error: #{e.message}")
@@ -173,6 +183,7 @@ module MjmlRb
 
     def extract_mjml_include_children(xml)
       include_doc = Document.new(sanitize_bare_ampersands(xml))
+      normalize_root_head_elements(include_doc)
       mjml_root = include_doc.root
       return [[], []] unless mjml_root&.name == "mjml"
 
@@ -219,6 +230,38 @@ module MjmlRb
       head
     end
 
+    def normalize_root_head_elements(doc)
+      mjml_root = doc.root
+      return unless mjml_root&.name == "mjml"
+
+      head_nodes = []
+      normalized_head_children = []
+      root_head_elements = []
+
+      mjml_root.children.each do |child|
+        next unless child.is_a?(Element)
+
+        if child.name == "mj-head"
+          head_nodes << child
+          child.children.each { |head_child| normalized_head_children << deep_clone(head_child) }
+        elsif ROOT_LEVEL_HEAD_TAGS.include?(child.name)
+          root_head_elements << child
+          normalized_head_children << deep_clone(child)
+        end
+      end
+
+      return if root_head_elements.empty? && head_nodes.length <= 1
+
+      head = head_nodes.first || ensure_head(doc)
+      return unless head
+
+      head.children.to_a.each { |child| head.delete(child) }
+      normalized_head_children.each { |child| head.add(child) }
+
+      root_head_elements.each { |child| mjml_root.delete(child) }
+      head_nodes.drop(1).each { |extra_head| mjml_root.delete(extra_head) }
+    end
+
     def strip_xml_declaration(content)
       content.sub(/\A<\?xml[^>]*\?>\s*/m, "")
     end
@@ -239,20 +282,74 @@ module MjmlRb
     end
 
     def wrap_ending_tags_in_cdata(content)
-      # Negative lookbehind (?<!\/) ensures self-closing tags like <mj-text ... /> are skipped
-      content.gsub(ENDING_TAGS_CDATA_RE) do
-        tag = Regexp.last_match(1)
-        attrs = Regexp.last_match(2).to_s
-        inner = Regexp.last_match(3).to_s
+      wrapped = +""
+      cursor = 0
+
+      while (match = ENDING_TAG_OPEN_RE.match(content, cursor))
+        tag = match[1]
+        attrs = match[2].to_s
+        wrapped << content[cursor...match.begin(0)]
+
+        closing_range = find_matching_ending_tag(content, tag, match.end(0))
+        unless closing_range
+          wrapped << match[0]
+          cursor = match.end(0)
+          next
+        end
+
+        inner = content[match.end(0)...closing_range.begin(0)]
         if inner.include?("<![CDATA[")
-          "<#{tag}#{attrs}>#{inner}</#{tag}>"
+          wrapped << "<#{tag}#{attrs}>#{inner}</#{tag}>"
         else
           # 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}>"
+          wrapped << "<#{tag}#{attrs}><![CDATA[#{escape_cdata(prepared)}]]></#{tag}>"
         end
+
+        cursor = closing_range.end(0)
       end
+
+      wrapped << content[cursor..] if cursor < content.length
+      wrapped
+    end
+
+    def find_matching_ending_tag(content, tag_name, cursor)
+      open_tag_re = /<#{Regexp.escape(tag_name)}(\s[^<>]*?)?(?<!\/)>/mi
+      close_tag_re = %r{</#{Regexp.escape(tag_name)}\s*>}i
+      depth = 1
+
+      while cursor < content.length
+        cdata_index = content.index("<![CDATA[", cursor)
+        open_match = open_tag_re.match(content, cursor)
+        close_match = close_tag_re.match(content, cursor)
+
+        candidates = []
+        candidates << [:cdata, cdata_index, nil] if cdata_index
+        candidates << [:open, open_match.begin(0), open_match] if open_match
+        candidates << [:close, close_match.begin(0), close_match] if close_match
+        return nil if candidates.empty?
+
+        kind, _, match = candidates.min_by { |candidate| candidate[1] }
+
+        case kind
+        when :cdata
+          cdata_end = content.index("]]>", cdata_index + 9)
+          return nil unless cdata_end
+
+          cursor = cdata_end + 3
+        when :open
+          depth += 1
+          cursor = match.end(0)
+        when :close
+          depth -= 1
+          return match if depth.zero?
+
+          cursor = match.end(0)
+        end
+      end
+
+      nil
     end
 
     def escape_cdata(content)
@@ -337,6 +434,7 @@ module MjmlRb
       attrs = element.attributes.each_with_object({}) do |(name, val), h|
         h[name] = val unless name.start_with?("data-mjml-")
       end
+      attrs["data-mjml-raw"] = "true" unless element.name.start_with?("mj-") || element.name == "mjml"
 
       # For ending-tag elements whose content was wrapped in CDATA, store
       # the raw HTML directly as content instead of parsing structurally.
@@ -358,7 +456,10 @@ module MjmlRb
           memo << element_to_ast(child, keep_comments: keep_comments)
         when Text
           text = child.value
-          memo << AstNode.new(tag_name: "#text", content: text) unless text.strip.empty?
+          next if text.empty?
+          next if text.strip.empty? && ignorable_whitespace_text?(text, parent_element_name: element.name)
+
+          memo << AstNode.new(tag_name: "#text", content: text)
         when Comment
           memo << AstNode.new(tag_name: "#comment", content: child.string) if keep_comments
         end
@@ -372,5 +473,11 @@ module MjmlRb
         file: meta_file
       )
     end
+
+    def ignorable_whitespace_text?(text, parent_element_name:)
+      return true if parent_element_name.start_with?("mj-") || parent_element_name == "mjml"
+
+      text.match?(/[\r\n]/)
+    end
   end
 end

data/lib/mjml-rb/renderer.rb

@@ -168,6 +168,8 @@ module MjmlRb
       HTML
 
       html = apply_inline_styles(html, context)
+      html = preserve_raw_tag_spacing(html)
+      html = strip_internal_raw_markers(html)
       html = merge_outlook_conditionals(html)
       before_doctype.empty? ? html : "#{before_doctype}\n#{html}"
     end
@@ -342,20 +344,27 @@ module MjmlRb
       return html if css_blocks.empty?
 
       document = parse_html_document(html)
-      rules, at_rules_css = parse_inline_css_rules(css_blocks.join("\n"))
+      rules, = parse_inline_css_rules(css_blocks.join("\n"))
+      merged_declarations_by_node = {}
+      touched_properties_by_node = Hash.new { |hash, node| hash[node] = Set.new }
 
       rules.each do |selector, declarations|
         next if selector.empty? || declarations.empty?
 
         select_nodes(document, selector).each do |node|
-          merge_inline_style!(node, declarations)
+          existing = merged_declarations_by_node[node] ||= begin
+            source = node["data-mjml-raw"] == "true" ? :inline : :css
+            parsed = parse_css_declarations(node["style"].to_s, source: source)
+            touched_properties_by_node[node].merge(parsed.keys & HTML_ATTRIBUTE_SYNC_PROPERTIES.to_a) if source == :inline
+            parsed
+          end
+          merge_inline_declarations!(existing, declarations, touched_properties_by_node[node])
         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)
+      merged_declarations_by_node.each do |node, declarations|
+        finalize_inline_style!(node, declarations, touched_properties_by_node[node])
+      end
 
       document.to_html
     end
@@ -368,18 +377,6 @@ 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
@@ -517,7 +514,7 @@ module MjmlRb
       [a, b, c]
     end
 
-    def parse_css_declarations(declarations)
+    def parse_css_declarations(declarations, source: :css)
       declarations.split(";").each_with_object({}) do |entry, memo|
         property, value = entry.split(":", 2).map { |part| part&.strip }
         next if property.nil? || property.empty? || value.nil? || value.empty?
@@ -525,35 +522,26 @@ module MjmlRb
         important = value.match?(/\s*!important\s*\z/)
         memo[property] = {
           value: value.sub(/\s*!important\s*\z/, "").strip,
-          important: important
+          important: important,
+          source: source
         }
       end
     end
 
-    def merge_inline_style!(node, declarations)
-      existing = parse_css_declarations(node["style"].to_s)
+    def merge_inline_declarations!(existing, declarations, touched_properties)
       declarations.each do |property, value|
         merged = merge_css_declaration(existing[property], value)
         next if merged.equal?(existing[property])
 
         existing.delete(property)
         existing[property] = merged
+        touched_properties << property
       end
-      normalize_background_fallbacks!(node, existing)
-      sync_html_attributes!(node, existing)
-      node["style"] = serialize_css_declarations(existing)
     end
 
-    def normalize_background_fallbacks!(node, declarations)
-      background_color = declaration_value(declarations["background-color"])
-      return if background_color.nil? || background_color.empty?
-
-      if syncable_background?(declaration_value(declarations["background"]))
-        declarations["background"] = {
-          value: background_color,
-          important: declarations.fetch("background-color", {}).fetch(:important, false)
-        }
-      end
+    def finalize_inline_style!(node, declarations, touched_properties)
+      sync_html_attributes!(node, declarations, touched_properties)
+      node["style"] = serialize_css_declarations(declarations)
     end
 
     # Sync HTML attributes from inlined CSS declarations.
@@ -569,15 +557,19 @@ module MjmlRb
       "text-align" => "align",
       "vertical-align" => "valign"
     }.freeze
+    HTML_ATTRIBUTE_SYNC_PROPERTIES = Set.new((%w[width height] + STYLE_TO_ATTRIBUTE.keys)).freeze
 
-    def sync_html_attributes!(node, declarations)
+    def sync_html_attributes!(node, declarations, touched_properties = nil)
       tag = node.name.downcase
 
       # Sync width/height on TABLE, TD, TH, IMG
       if WIDTH_HEIGHT_ELEMENTS.include?(tag)
         %w[width height].each do |prop|
+          next if touched_properties && !touched_properties.include?(prop)
+
           css_value = declaration_value(declarations[prop])
           next if css_value.nil? || css_value.empty?
+          next if tag == "img" && prop == "width" && css_value.include?("%")
 
           # Convert CSS px values to plain numbers for HTML attributes;
           # keep other values (auto, %) as-is.
@@ -589,6 +581,8 @@ module MjmlRb
       # Sync style-to-attribute mappings on table elements
       if TABLE_ELEMENTS.include?(tag)
         STYLE_TO_ATTRIBUTE.each do |css_prop, html_attr|
+          next if touched_properties && !touched_properties.include?(css_prop)
+
           css_value = declaration_value(declarations[css_prop])
           next if css_value.nil? || css_value.empty?
 
@@ -609,26 +603,10 @@ module MjmlRb
       end
     end
 
-    def syncable_background?(value)
-      return true if value.nil? || value.empty?
-
-      normalized = value.downcase
-      !normalized.include?("url(") &&
-        !normalized.include?("gradient(") &&
-        !normalized.include?("/") &&
-        !normalized.include?(" no-repeat") &&
-        !normalized.include?(" repeat") &&
-        !normalized.include?(" fixed") &&
-        !normalized.include?(" scroll") &&
-        !normalized.include?(" center") &&
-        !normalized.include?(" top") &&
-        !normalized.include?(" bottom") &&
-        !normalized.include?(" left") &&
-        !normalized.include?(" right")
-    end
-
     def merge_css_declaration(existing, incoming)
       return incoming if existing.nil?
+      return incoming if incoming[:important] && !existing[:important]
+      return existing if existing[:source] == :inline
       return existing if existing[:important] && !incoming[:important]
 
       incoming
@@ -639,13 +617,49 @@ module MjmlRb
     end
 
     def serialize_css_declarations(declarations)
-      declarations.map do |property, declaration|
-        value = declaration[:value]
-        value = "#{value} !important" if declaration[:important]
-        "#{property}: #{value}"
+      ordered_css_declarations(declarations).map do |property, declaration|
+        "#{property}: #{declaration[:value]}"
       end.join("; ")
     end
 
+    SHORTHAND_LONGHAND_FAMILIES = {
+      "background" => /\Abackground-/,
+      "border" => /\Aborder(?:-(?!collapse|spacing)[a-z-]+)?\z/,
+      "border-radius" => /\Aborder-(?:top|bottom)-(?:left|right)-radius\z/,
+      "font" => /\Afont-/,
+      "list-style" => /\Alist-style-/,
+      "margin" => /\Amargin-(?:top|right|bottom|left)\z/,
+      "padding" => /\Apadding-(?:top|right|bottom|left)\z/
+    }.freeze
+
+    def ordered_css_declarations(declarations)
+      ordered = declarations.to_a
+
+      SHORTHAND_LONGHAND_FAMILIES.each do |shorthand, longhand_pattern|
+        family_indexes = ordered.each_index.select do |index|
+          property = ordered[index][0]
+          property == shorthand || property.match?(longhand_pattern)
+        end
+        next if family_indexes.length < 2
+
+        family_entries = family_indexes.map.with_index do |declaration_index, original_family_index|
+          [ordered[declaration_index], original_family_index]
+        end
+        next unless family_entries.any? { |((_, declaration), _)| declaration[:important] }
+        next unless family_entries.any? { |((_, declaration), _)| !declaration[:important] }
+
+        reordered_entries = family_entries.sort_by do |((_, declaration), original_family_index)|
+          [declaration[:important] ? 1 : 0, original_family_index]
+        end.map(&:first)
+
+        family_indexes.each_with_index do |declaration_index, reordered_index|
+          ordered[declaration_index] = reordered_entries[reordered_index]
+        end
+      end
+
+      ordered
+    end
+
     def append_component_head_styles(document, context)
       all_tags = collect_tag_names(document)
 
@@ -740,7 +754,7 @@ module MjmlRb
       if node.respond_to?(:children)
         node.children.map do |child|
           if child.text?
-            escape_html(child.content.to_s)
+            serialize_text_content(escape_html(child.content.to_s))
           elsif child.comment?
             "<!--#{child.content}-->"
           else
@@ -759,7 +773,7 @@ module MjmlRb
       if node.respond_to?(:children)
         node.children.map do |child|
           if child.text?
-            child.content.to_s
+            serialize_text_content(child.content.to_s)
           elsif child.comment?
             "<!--#{child.content}-->"
           else
@@ -771,15 +785,52 @@ module MjmlRb
       end
     end
 
+    def annotate_raw_html(content)
+      return content if content.nil? || content.empty? || !content.include?("<")
+      content.gsub(/<(?!\/|!)([A-Za-z][\w:-]*)(\s[^<>]*?)?(\s*\/?)>/) do
+        tag_name = Regexp.last_match(1)
+        attrs = Regexp.last_match(2).to_s
+        closing = Regexp.last_match(3).to_s
+        "<#{tag_name}#{attrs} data-mjml-raw=\"true\"#{closing}>"
+      end
+    end
+
+    def strip_internal_raw_markers(html)
+      html.gsub(/\sdata-mjml-raw=(['"])true\1/, "")
+    end
+
+    def preserve_raw_tag_spacing(html)
+      html.gsub(
+        /(<[^>]+data-mjml-raw=(['"])true\2[^>]*>)([ \t]+)(<[^\/!][^>]+data-mjml-raw=(['"])true\5[^>]*>)/
+      ) do
+        "#{Regexp.last_match(1)}#{encode_whitespace_entities(Regexp.last_match(3))}#{Regexp.last_match(4)}"
+      end
+    end
+
+    def encode_whitespace_entities(text)
+      text.to_s.gsub(" ", "&#32;").gsub("\t", "&#9;")
+    end
+
     def serialize_node(node)
       attrs = node.attributes.map { |k, v| %( #{k}="#{escape_attr(v)}") }.join
       return "<#{node.tag_name}#{attrs} />" if node.children.empty? && html_void_tag?(node.tag_name)
       return "<#{node.tag_name}#{attrs}></#{node.tag_name}>" if node.children.empty?
 
-      inner = node.children.map { |child| child.text? ? child.content.to_s : serialize_node(child) }.join
+      inner = node.children.map { |child| child.text? ? serialize_text_content(child.content.to_s) : serialize_node(child) }.join
       "<#{node.tag_name}#{attrs}>#{inner}</#{node.tag_name}>"
     end
 
+    def serialize_text_content(text)
+      value = text.to_s
+      return value unless significant_whitespace_text?(value)
+
+      value.gsub(" ", "&#32;").gsub("\t", "&#9;")
+    end
+
+    def significant_whitespace_text?(text)
+      !text.empty? && text.strip.empty? && !text.match?(/[\r\n]/)
+    end
+
     def html_void_tag?(tag_name)
       HTML_VOID_TAGS.include?(tag_name.to_s.downcase)
     end

data/lib/mjml-rb/version.rb

@@ -1,3 +1,3 @@
 module MjmlRb
-  VERSION = "0.4.2".freeze
+  VERSION = "0.4.4".freeze
 end

metadata

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