mjml-rb 0.2.37 → 0.2.39

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 022de3642d6473c98ee598b12dd209cb4f6cfb8f6ce50a230768a9e29a6506e3
-  data.tar.gz: 786a9cad787fb6f3d3a305f5a7dae786387822a55c67d9d58bf489a63f5e4a34
+  metadata.gz: c7864f17e62acc702b5da45e9ca4322bc5207d486190de2ae7bab1a19e5109be
+  data.tar.gz: 9a5587f0f059d2d422407d65ad149e0d1ba04b731409a42290d3b4aa2aa34fc3
 SHA512:
-  metadata.gz: 30ee8b1a6c75a23db416db7b7f41e0881b8e80c2bca25d097ba622159909e07dd2a0ccb801caff5bb78c3c50b4f3a1bab09c26ff419f51094957e54bddbd5b30
-  data.tar.gz: 4a1550e5f7d6862abf6c2a3836f3b622b1c21027af1869558e4a8122671d738ba26174ad92ab0bbdf35c651c476240f107b1a27bd4fd61460630bd0e66b7044e
+  metadata.gz: a910ab3a64a41505e662a31c97ad11b29a72bee403c5e98b70a2abafa7fee0e056a173e55232bde1d8a5b765a524a6acf1a99d0536c0c74a49ef67dcaa17265b
+  data.tar.gz: 0d9e9e08cfc38bcde65ba9480ca5a10365b0ecc60a20695a57cbc027dbe4a86df6d92424d46597d2ae8c46c7e25f6e4ccb6575d6d43f0d4dd157c54939afec36

data/README.md

@@ -12,12 +12,20 @@
 > feedback, bug reports, test cases, optimizations, proposals, and pull requests.
 > No warranty of any kind is provided.
 
-This directory contains a Ruby-first implementation of the main MJML user-facing tooling:
+This gem provides a Ruby-first implementation of the main MJML tooling:
 
 - library API compatible with `mjml2html`
 - command-line interface (`mjml`)
-- migration and validation commands
-- pure Ruby parser + AST + renderer (no external native renderer dependency)
+- validation commands
+- pure Ruby parser, AST, validator, and renderer
+- no Node.js runtime and no shelling out to the official npm renderer
+
+## Compatibility
+
+This project targets **MJML v4 only**.
+
+- parsing, validation, and rendering are implemented against the MJML v4 document structure
+- component rules and attribute validation follow the MJML v4 model
 
 ## Quick start
 
@@ -31,19 +39,115 @@ bundle exec ruby -Ilib -e 'require "mjml-rb"; puts MjmlRb.mjml2html("<mjml><mj-b
 ```bash
 bundle exec bin/mjml example.mjml -o output.html
 bundle exec bin/mjml --validate example.mjml
-bundle exec bin/mjml --migrate old.mjml -s
 ```
 
-## Implementation idea
+## 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.
+
+If you want Slim-backed MJML templates, configure it explicitly:
+
+```ruby
+config.mjml_rb.template_language = :slim
+```
+
+Supported values are `:erb`, `:slim`, and `:haml`.
+
+With a configured `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.
+
+Create a view such as `app/views/user_mailer/welcome.html.mjml`:
+
+```mjml
+<mjml>
+  <mj-body>
+    <mj-section>
+      <mj-column>
+        <mj-text>Hello from Rails</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")
+  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" }
+```
+
+## Architecture
+
+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
+```
+
+If you want the full internal walkthrough, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## Implementation goal
 
-> **Zero-dependency pure-Ruby MJML renderer.**
+> **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 native extensions and no Node.js
-> dependency. Drop it into a Rails, Sinatra, or plain Ruby project and render
-> MJML templates the same way you render ERB — no extra runtime, no
+> 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`.
 
-Remaining parity work is tracked in [npm ↔ Ruby Parity Audit](/docs/PARITY_AUDIT.md).
+Remaining parity work is tracked in [npm ↔ Ruby Parity Audit](docs/PARITY_AUDIT.md).

data/lib/mjml-rb/cli.rb

@@ -4,7 +4,6 @@ require "pathname"
 require "time"
 
 require_relative "compiler"
-require_relative "migrator"
 require_relative "version"
 
 module MjmlRb
@@ -58,7 +57,6 @@ module MjmlRb
     def default_options
       {
         read: [],
-        migrate: [],
         validate: [],
         watch: [],
         stdin: false,
@@ -77,7 +75,6 @@ module MjmlRb
         opts.banner = "Usage: mjml [options] [files]"
 
         opts.on("-r", "--read FILES", Array, "Compile MJML files") { |v| options[:read].concat(v) }
-        opts.on("-m", "--migrate FILES", Array, "Migrate MJML3 files") { |v| options[:migrate].concat(v) }
         opts.on("-v", "--validate FILES", Array, "Validate MJML files") { |v| options[:validate].concat(v) }
         opts.on("-w", "--watch FILES", Array, "Watch and compile files when modified") { |v| options[:watch].concat(v) }
         opts.on("-i", "--stdin", "Read MJML from stdin") { options[:stdin] = true }
@@ -148,7 +145,6 @@ module MjmlRb
     def resolve_input(options)
       inputs = {}
       inputs[:read] = options[:read] unless options[:read].empty?
-      inputs[:migrate] = options[:migrate] unless options[:migrate].empty?
       inputs[:validate] = options[:validate] unless options[:validate].empty?
       inputs[:watch] = options[:watch] unless options[:watch].empty?
       inputs[:stdin] = true if options[:stdin]
@@ -183,9 +179,6 @@ module MjmlRb
 
     def process_input(input, mode, config)
       case mode
-      when :migrate
-        html = Migrator.new.migrate(input[:mjml])
-        { file: input[:file], compiled: Result.new(html: html) }
       when :validate
         compiler = Compiler.new(config.merge(validation_level: "strict"))
         { file: input[:file], compiled: compiler.compile(input[:mjml]) }

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

@@ -61,7 +61,7 @@ module MjmlRb
         "font-size" => "unit(px)",
         "font-family" => "string",
         "font-weight" => "string",
-        "letter-spacing" => "unit(px,em)",
+        "letter-spacing" => "unitWithNegative(px,em)",
         "line-height" => "unit(px,%,)",
         "color" => "color",
         "padding-bottom" => "unit(px,%)",

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

@@ -25,7 +25,7 @@ module MjmlRb
         "name" => "string",
         "title" => "string",
         "inner-padding" => "unit(px,%){1,4}",
-        "letter-spacing" => "unit(px,em)",
+        "letter-spacing" => "unitWithNegative(px,em)",
         "line-height" => "unit(px,%,)",
         "padding-bottom" => "unit(px,%)",
         "padding-left" => "unit(px,%)",

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

@@ -7,7 +7,7 @@ module MjmlRb
 
       ALLOWED_ATTRIBUTES = {
         "mj-style" => {
-          "inline" => "string"
+          "inline" => "enum(inline)"
         },
         "mj-font" => {
           "name" => "string",

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

@@ -6,7 +6,7 @@ module MjmlRb
       TAGS = ["mj-hero"].freeze
 
       ALLOWED_ATTRIBUTES = {
-        "mode" => "string",
+        "mode" => "enum(fixed-height,fluid-height)",
         "height" => "unit(px,%)",
         "background-url" => "string",
         "background-width" => "unit(px,%)",

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

@@ -10,7 +10,7 @@ module MjmlRb
       NAVBAR_ALLOWED_ATTRIBUTES = {
         "align" => "enum(left,center,right)",
         "base-url" => "string",
-        "hamburger" => "string",
+        "hamburger" => "enum(hamburger)",
         "ico-align" => "enum(left,center,right)",
         "ico-open" => "string",
         "ico-close" => "string",
@@ -29,7 +29,7 @@ module MjmlRb
         "padding-right" => "unit(px,%)",
         "padding-bottom" => "unit(px,%)",
         "ico-text-decoration" => "string",
-        "ico-line-height" => "unit(px,%)"
+        "ico-line-height" => "unit(px,%,)"
       }.freeze
 
       NAVBAR_LINK_ALLOWED_ATTRIBUTES = {
@@ -42,8 +42,8 @@ module MjmlRb
         "name" => "string",
         "target" => "string",
         "rel" => "string",
-        "letter-spacing" => "string",
-        "line-height" => "unit(px,%)",
+        "letter-spacing" => "unitWithNegative(px,em)",
+        "line-height" => "unit(px,%,)",
         "padding-bottom" => "unit(px,%)",
         "padding-left" => "unit(px,%)",
         "padding-right" => "unit(px,%)",

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

@@ -8,23 +8,23 @@ module MjmlRb
       ALLOWED_ATTRIBUTES = {
         "align" => "enum(left,right,center)",
         "border" => "string",
-        "cellpadding" => "string",
-        "cellspacing" => "string",
+        "cellpadding" => "integer",
+        "cellspacing" => "integer",
         "color" => "color",
         "container-background-color" => "color",
         "font-family" => "string",
-        "font-size" => "string",
+        "font-size" => "unit(px)",
         "font-weight" => "string",
-        "line-height" => "string",
+        "line-height" => "unit(px,%,)",
         "padding" => "unit(px,%){1,4}",
         "padding-top" => "unit(px,%)",
         "padding-right" => "unit(px,%)",
         "padding-bottom" => "unit(px,%)",
         "padding-left" => "unit(px,%)",
-        "role" => "string",
-        "table-layout" => "enum(auto,fixed)",
+        "role" => "enum(none,presentation)",
+        "table-layout" => "enum(auto,fixed,initial,inherit)",
         "vertical-align" => "enum(top,bottom,middle)",
-        "width" => "string"
+        "width" => "unit(px,%,auto)"
       }.freeze
 
       DEFAULTS = {

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

@@ -11,12 +11,12 @@ module MjmlRb
         "color" => "color",
         "container-background-color" => "color",
         "font-family" => "string",
-        "font-size" => "string",
+        "font-size" => "unit(px)",
         "font-style" => "string",
         "font-weight" => "string",
-        "height" => "string",
-        "letter-spacing" => "string",
-        "line-height" => "string",
+        "height" => "unit(px,%)",
+        "letter-spacing" => "unitWithNegative(px,em)",
+        "line-height" => "unit(px,%,)",
         "padding" => "unit(px,%){1,4}",
         "padding-top" => "unit(px,%)",
         "padding-right" => "unit(px,%)",

data/lib/mjml-rb/railtie.rb

@@ -0,0 +1,18 @@
+require_relative "template_handler"
+
+module MjmlRb
+  class Railtie < Rails::Railtie
+    config.mjml_rb = ActiveSupport::OrderedOptions.new
+    config.mjml_rb.compiler_options = {validation_level: "strict"}
+    config.mjml_rb.template_language = nil
+
+    initializer "mjml_rb.action_view" do |app|
+      MjmlRb.rails_compiler_options = app.config.mjml_rb.compiler_options.to_h
+      MjmlRb.rails_template_language = app.config.mjml_rb.template_language
+
+      ActiveSupport.on_load(:action_view) do
+        MjmlRb.register_action_view_template_handler!
+      end
+    end
+  end
+end

data/lib/mjml-rb/renderer.rb

@@ -209,7 +209,7 @@ module MjmlRb
 
     def render_node(node, context, parent:)
       return escape_html(node.content.to_s) if node.text?
-      return "" if node.comment?
+      return "<!--#{node.content}-->" if node.comment?
 
       attrs = resolved_attributes(node, context)
       if (component = component_for(node.tag_name))

data/lib/mjml-rb/template_handler.rb

@@ -0,0 +1,114 @@
+module MjmlRb
+  class TemplateHandler
+    MJML_CAPTURE_DEPTH_IVAR = :@_mjml_rb_capture_depth
+    TEMPLATE_ENGINES = {
+      slim: {
+        require: "slim",
+        gem_name: "slim"
+      },
+      haml: {
+        require: "haml",
+        gem_name: "haml"
+      }
+    }.freeze
+
+    class << self
+      def call(template, source = nil)
+        <<~RUBY
+          ::MjmlRb::TemplateHandler.render(self, #{template.source.inspect}, #{template.identifier.inspect}, local_assigns)
+        RUBY
+      end
+
+      def render(view_context, source, identifier, local_assigns = {})
+        if capture_mode?(view_context)
+          return mark_html_safe(render_source(view_context, source, local_assigns))
+        end
+
+        with_capture_mode(view_context) do
+          mjml_source = render_source(view_context, source, local_assigns).to_s
+          mjml_result = ::MjmlRb::Compiler.new(::MjmlRb.rails_compiler_options || {}).compile(mjml_source)
+
+          if mjml_result.errors.any?
+            raise "MJML compilation failed for #{identifier}: #{mjml_result.errors.map { |error| error[:formatted_message] || error[:message] }.join(', ')}"
+          end
+
+          mark_html_safe(mjml_result.html.to_s)
+        end
+      end
+
+      private
+
+      def render_source(view_context, source, local_assigns)
+        language = ::MjmlRb.rails_template_language
+        if language.nil?
+          stripped_source = source.to_s.lstrip
+          return source.to_s if stripped_source.start_with?("<")
+
+          raise "MJML Rails template_language is not configured for non-XML templates. Supported values: nil, :erb, :slim, :haml"
+        end
+
+        case language
+        when :erb
+          render_erb_source(view_context, source.to_s, local_assigns)
+        when :slim, :haml
+          render_template_language_source(view_context, source.to_s, local_assigns, language)
+        else
+          raise "Unsupported MJML Rails template_language `#{language}`. Supported values: nil, :erb, :slim, :haml"
+        end
+      end
+
+      def render_erb_source(view_context, source, local_assigns)
+        require "erb"
+
+        local_assigns.each do |name, value|
+          define_local_reader(view_context, name, value)
+        end
+
+        erb = ::ERB.new(source)
+        erb.result(view_context.instance_eval { binding })
+      end
+
+      def render_template_language_source(view_context, source, local_assigns, language)
+        engine = TEMPLATE_ENGINES.fetch(language)
+        require engine[:require]
+
+        case language
+        when :slim
+          ::Slim::Template.new { source }.render(view_context, local_assigns.transform_keys(&:to_sym))
+        when :haml
+          if defined?(::Haml::Template)
+            ::Haml::Template.new { source }.render(view_context, local_assigns.transform_keys(&:to_sym))
+          else
+            raise "MJML Rails template_language is set to :haml, but this Haml version does not expose Haml::Template"
+          end
+        end
+      rescue LoadError
+        raise "MJML Rails template_language is set to :#{language}, but the `#{engine[:gem_name]}` gem is not available"
+      end
+
+      def define_local_reader(view_context, name, value)
+        singleton_class = class << view_context; self; end
+        singleton_class.send(:define_method, name) do
+          value
+        end
+      end
+
+      def capture_mode?(view_context)
+        view_context.instance_variable_get(MJML_CAPTURE_DEPTH_IVAR).to_i.positive?
+      end
+
+      def with_capture_mode(view_context)
+        depth = view_context.instance_variable_get(MJML_CAPTURE_DEPTH_IVAR).to_i
+        view_context.instance_variable_set(MJML_CAPTURE_DEPTH_IVAR, depth + 1)
+        yield
+      ensure
+        next_depth = view_context.instance_variable_get(MJML_CAPTURE_DEPTH_IVAR).to_i - 1
+        view_context.instance_variable_set(MJML_CAPTURE_DEPTH_IVAR, [next_depth, 0].max)
+      end
+
+      def mark_html_safe(value)
+        value.respond_to?(:html_safe) ? value.html_safe : value
+      end
+    end
+  end
+end

data/lib/mjml-rb/validator.rb

@@ -160,8 +160,13 @@ module MjmlRb
         color?(value)
       when /\Aenum\((.+)\)\z/
         Regexp.last_match(1).split(",").map(&:strip).include?(value)
+      when /\AunitWithNegative\((.+)\)(?:\{(\d+),(\d+)\})?\z/
+        units = Regexp.last_match(1).split(",", -1).map(&:strip)
+        min_count = Regexp.last_match(2)&.to_i || 1
+        max_count = Regexp.last_match(3)&.to_i || 1
+        unit_values?(value, units, min_count: min_count, max_count: max_count)
       when /\Aunit\((.+)\)(?:\{(\d+),(\d+)\})?\z/
-        units = Regexp.last_match(1).split(",").map(&:strip)
+        units = Regexp.last_match(1).split(",", -1).map(&:strip)
         min_count = Regexp.last_match(2)&.to_i || 1
         max_count = Regexp.last_match(3)&.to_i || 1
         unit_values?(value, units, min_count: min_count, max_count: max_count)
@@ -188,7 +193,11 @@ module MjmlRb
       return true if value.match?(/\A0(?:\.0+)?\z/)
 
       units.any? do |unit|
-        value == unit || value.match?(/\A-?\d+(?:\.\d+)?#{Regexp.escape(unit)}\z/)
+        if unit.empty?
+          value.match?(/\A-?\d+(?:\.\d+)?\z/)
+        else
+          value == unit || value.match?(/\A-?\d+(?:\.\d+)?#{Regexp.escape(unit)}\z/)
+        end
       end
     end
 

data/lib/mjml-rb/version.rb

@@ -1,3 +1,3 @@
 module MjmlRb
-  VERSION = "0.2.37".freeze
+  VERSION = "0.2.39".freeze
 end

data/lib/mjml-rb.rb

@@ -6,7 +6,6 @@ require_relative "mjml-rb/parser"
 require_relative "mjml-rb/renderer"
 require_relative "mjml-rb/compiler"
 require_relative "mjml-rb/validator"
-require_relative "mjml-rb/migrator"
 require_relative "mjml-rb/cli"
 
 module MjmlRb
@@ -21,6 +20,29 @@ module MjmlRb
   WARNING
 
   class << self
+    def rails_compiler_options
+      @rails_compiler_options ||= {validation_level: "strict"}
+    end
+
+    def rails_compiler_options=(options)
+      @rails_compiler_options = options || {}
+    end
+
+    def rails_template_language
+      @rails_template_language
+    end
+
+    def rails_template_language=(language)
+      @rails_template_language = language&.to_sym
+    end
+
+    def register_action_view_template_handler!
+      return unless defined?(ActionView::Template)
+
+      require_relative "mjml-rb/template_handler"
+      ActionView::Template.register_template_handler(:mjml, TemplateHandler)
+    end
+
     def mjml2html(mjml, options = {})
       Compiler.new(options).compile(mjml).to_h
     end
@@ -28,3 +50,9 @@ module MjmlRb
     alias to_html mjml2html
   end
 end
+
+MjmlRb.register_action_view_template_handler! if defined?(ActionView::Template)
+
+if defined?(Rails::Railtie)
+  require_relative "mjml-rb/railtie"
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mjml-rb
 version: !ruby/object:Gem::Version
-  version: 0.2.37
+  version: 0.2.39
 platform: ruby
 authors:
 - Andrei Andriichuk
@@ -76,10 +76,11 @@ files:
 - lib/mjml-rb/components/table.rb
 - lib/mjml-rb/components/text.rb
 - lib/mjml-rb/dependencies.rb
-- lib/mjml-rb/migrator.rb
 - lib/mjml-rb/parser.rb
+- lib/mjml-rb/railtie.rb
 - lib/mjml-rb/renderer.rb
 - lib/mjml-rb/result.rb
+- lib/mjml-rb/template_handler.rb
 - lib/mjml-rb/validator.rb
 - lib/mjml-rb/version.rb
 - mjml-rb.gemspec

data/lib/mjml-rb/migrator.rb

@@ -1,18 +0,0 @@
-module MjmlRb
-  class Migrator
-    TAG_RENAMES = {
-      "mj-container" => "mj-body"
-    }.freeze
-
-    def migrate(mjml)
-      output = mjml.to_s.dup
-
-      TAG_RENAMES.each do |from, to|
-        output.gsub!("<#{from}", "<#{to}")
-        output.gsub!("</#{from}>", "</#{to}>")
-      end
-
-      output
-    end
-  end
-end