mjml-rb 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfa6cc54a797f8b4323003dbcfd92fa4ef02b1e0b118e58acd14bb8e901e502d
-  data.tar.gz: 12d0fb1d71e03a23811caac5b0417b7f32823b95870e47296ea51fd8bd713018
+  metadata.gz: 2a961ff4aa96b2bc79520f261eb233c0e8b77f363afa3d7e0c670fa622359ab7
+  data.tar.gz: 295a1289237c408dbcd2752c26bc45c9b16dd80edfe00933bcec864bf250bebf
 SHA512:
-  metadata.gz: 689a1974e1c6e7477e202c3fb070c63eadf3b66617e2ea177feb6b45ae9d58cf9c1472dd7ddbe4e141d6583e67f83c93f76ca91c5f787d4a706241523c313361
-  data.tar.gz: ad73e16bd469bdfd98ccff031aca1796f99c460c87ab6435ba272492ffeb4ffff2b1e77f1019c368324286942cc561239e20b4219e6010efcac7d2066a945bb6
+  metadata.gz: e544b134c2db7296c58cd9a5c6235b5780448a3673618ae5392ca6eeada84cafa67d88ad7cf1e8aab99aa41ab92feabcc3255ec7eb30ccdbd386b52cc73515ba
+  data.tar.gz: 3751e0e61fcfd95378c03d1024caa4dcc4ccc0e7dd1f92a08108afe98c5858cff3d2c31e8a551185a145c44e36e96d7d934fcfc4cd86168fad8ec74650192661

data/README.md

@@ -95,6 +95,59 @@ compiler options in your application config:
 config.mjml_rb.compiler_options = { validation_level: "soft" }
 ```
 
+## Custom components
+
+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:
+
+```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)
+```
+
 ## Architecture
 
 The compile pipeline is intentionally simple and fully Ruby-based:

data/lib/mjml-rb/cli.rb

@@ -24,6 +24,11 @@ module MjmlRb
       parser.parse!(argv)
       options[:positional] = argv
 
+      rc_config = ConfigFile.load
+      if rc_config[:options]
+        options[:config] = rc_config[:options].merge(options[:config])
+      end
+
       input_mode, input_values = resolve_input(options)
       output_mode = resolve_output(options)
       config = options[:config]

data/lib/mjml-rb/component_registry.rb

@@ -0,0 +1,65 @@
+require "set"
+
+module MjmlRb
+  class ComponentRegistry
+    attr_reader :custom_components, :custom_dependencies, :custom_ending_tags
+
+    def initialize
+      @custom_components = []
+      @custom_dependencies = {}
+      @custom_ending_tags = Set.new
+    end
+
+    def register(klass, dependencies: {}, ending_tags: [])
+      validate_component!(klass)
+      @custom_components << klass unless @custom_components.include?(klass)
+      dependencies.each do |parent, children|
+        @custom_dependencies[parent] = ((@custom_dependencies[parent] || []) + Array(children)).uniq
+      end
+      @custom_ending_tags.merge(Array(ending_tags))
+    end
+
+    def component_class_for_tag(tag_name)
+      all_component_classes.find { |klass| klass.tags.include?(tag_name) }
+    end
+
+    def dependency_rules
+      merged = {}
+      Dependencies::RULES.each { |k, v| merged[k] = v.dup }
+      @custom_dependencies.each do |parent, children|
+        merged[parent] = ((merged[parent] || []) + Array(children)).uniq
+      end
+      merged
+    end
+
+    def ending_tags
+      Dependencies::ENDING_TAGS | @custom_ending_tags
+    end
+
+    def reset!
+      @custom_components.clear
+      @custom_dependencies.clear
+      @custom_ending_tags.clear
+    end
+
+    private
+
+    def all_component_classes
+      builtin = MjmlRb::Components.constants.filter_map do |name|
+        value = MjmlRb::Components.const_get(name)
+        value if value.is_a?(Class) && value < MjmlRb::Components::Base
+      rescue NameError
+        nil
+      end
+      (builtin + @custom_components).uniq
+    end
+
+    def validate_component!(klass)
+      raise ArgumentError, "Expected a Class, got #{klass.class}" unless klass.is_a?(Class)
+      unless klass.respond_to?(:tags) && klass.respond_to?(:allowed_attributes)
+        raise ArgumentError, "Component class must respond to .tags and .allowed_attributes (inherit from MjmlRb::Components::Base)"
+      end
+      raise ArgumentError, "Component must define at least one tag via TAGS" if klass.tags.empty?
+    end
+  end
+end

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

@@ -39,6 +39,7 @@ module MjmlRb
 
       def render(tag_name:, node:, context:, attrs:, parent:)
         width_pct = context.delete(:_column_width_pct) || 100.0
+        mobile_width = context.delete(:_column_mobile_width)
         css_class = attrs["css-class"]
         a = self.class.default_attributes.merge(attrs)
 
@@ -63,7 +64,7 @@ module MjmlRb
           "direction" => a["direction"],
           "display" => "inline-block",
           "vertical-align" => vertical_align,
-          "width" => "100%"
+          "width" => (mobile_width ? mobile_width_value(a, width_pct, context[:container_width]) : "100%")
         )
 
         column_markup =
@@ -168,6 +169,22 @@ module MjmlRb
         value && !value.empty?
       end
 
+      def mobile_width_value(attrs, width_pct, parent_width)
+        width = attrs["width"]
+
+        if present_attr?(width) && width.end_with?("%")
+          width
+        elsif present_attr?(width) && width.end_with?("px")
+          parent_width_px = parse_pixel_value(parent_width || "600px")
+          return "100%" if parent_width_px.zero?
+
+          percentage = (parse_pixel_value(width) / parent_width_px) * 100
+          "#{percentage.to_s.sub(/\.?0+$/, "")}%"
+        else
+          "#{width_pct.to_f.to_s.sub(/\.?0+$/, "")}%"
+        end
+      end
+
       def with_child_container_width(context, attrs, width_pct)
         previous_container_width = context[:container_width]
         context[:container_width] = child_container_width(context, attrs, width_pct)

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

@@ -77,6 +77,7 @@ module MjmlRb
               width_pct = widths[column_index] || 100.0
               column_index += 1
               context[:_column_width_pct] = width_pct
+              context[:_column_mobile_width] = true
               td_style = style_join(
                 "vertical-align" => resolved_attributes(child, context)["vertical-align"] || "top",
                 "width" => "#{(group_width_px * width_pct / 100.0).round}px"

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

@@ -238,11 +238,11 @@ module MjmlRb
       def hero_container_width(attrs, container_width)
         width = parse_unit_value(container_width)
         content_width = width - padding_side(attrs, "left") - padding_side(attrs, "right")
-        "#{[content_width, 0].max}px"
+        px_length([content_width, 0].max)
       end
 
       def normalize_container_width(value)
-        "#{parse_unit_value(value)}px"
+        px_length(parse_unit_value(value))
       end
 
       def padding_side(attrs, side)
@@ -280,6 +280,17 @@ module MjmlRb
       def blank?(value)
         value.nil? || value.to_s.empty?
       end
+
+      def px_length(value)
+        "#{format_number(value)}px"
+      end
+
+      def format_number(value)
+        number = value.to_f
+        return number.to_i.to_s if number == number.to_i
+
+        number.to_s.sub(/\.?0+$/, "")
+      end
     end
   end
 end

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

@@ -64,7 +64,7 @@ module MjmlRb
           render_wrapper(node, context, attrs)
         else
           a = self.class.default_attributes.merge(attrs)
-          if a["full-width"] == "full-width"
+          if a["full-width"] == "full-width" && !context[:_inside_full_width_wrapper]
             render_full_width_section(node, context, a)
           else
             render_section(node, context, a)
@@ -254,8 +254,8 @@ module MjmlRb
 
         # Build v:fill attributes
         fill_pairs = [
-          ["origin", "#{v_origin_x}, #{v_origin_y}"],
-          ["position", "#{v_pos_x}, #{v_pos_y}"],
+          ["origin", "#{format_vml_number(v_origin_x)}, #{format_vml_number(v_origin_y)}"],
+          ["position", "#{format_vml_number(v_pos_x)}, #{format_vml_number(v_pos_y)}"],
           ["src", bg_url],
           ["color", bg_color],
           ["type", vml_type]
@@ -287,6 +287,13 @@ module MjmlRb
         end
       end
 
+      def format_vml_number(value)
+        number = value.to_f
+        return number.to_i.to_s if number == number.to_i
+
+        number.to_s.sub(/\.?0+$/, "")
+      end
+
       def vml_size_attributes(bg_size)
         case bg_size
         when "cover"
@@ -639,7 +646,9 @@ module MjmlRb
         box_width    = container_px - pad_left - pad_right - border_left - border_right
 
         previous_container_width = context[:container_width]
+        previous_full_width_wrapper = context[:_inside_full_width_wrapper]
         context[:container_width] = "#{box_width}px"
+        context[:_inside_full_width_wrapper] = full_width
 
         div_attrs = {"class" => (full_width ? nil : css_class), "style" => div_style}
         inner = merge_outlook_conditionals(render_wrapped_children_wrapper(node, context, container_px, a["gap"]))
@@ -686,6 +695,7 @@ module MjmlRb
         end
       ensure
         context[:container_width] = previous_container_width if previous_container_width
+        context[:_inside_full_width_wrapper] = previous_full_width_wrapper
       end
 
       # Wrap each child mj-section/mj-wrapper in an Outlook conditional <tr><td>.
@@ -703,7 +713,7 @@ module MjmlRb
             child_attrs = resolved_attributes(child, context)
             child_css   = child_attrs["css-class"]
             outlook_class = suffix_css_classes(child_css)
-            td_open  = %(<!--[if mso | IE]><tr><td class="#{escape_attr(outlook_class)}" width="#{container_px}px" ><![endif]-->)
+            td_open  = %(<!--[if mso | IE]><tr><td class="#{escape_attr(outlook_class)}" width="#{container_px}" ><![endif]-->)
             td_close = %(<!--[if mso | IE]></td></tr><![endif]-->)
             child_html = with_wrapper_child_gap(context, index.zero? ? nil : gap) do
               render_node(child, context, parent: "mj-wrapper")

data/lib/mjml-rb/config_file.rb

@@ -0,0 +1,34 @@
+require "json"
+
+module MjmlRb
+  class ConfigFile
+    DEFAULT_NAME = ".mjmlrc"
+
+    def self.load(dir = Dir.pwd)
+      path = File.join(dir, DEFAULT_NAME)
+      return {} unless File.exist?(path)
+
+      raw = JSON.parse(File.read(path))
+      config = {}
+
+      if raw["packages"].is_a?(Array)
+        raw["packages"].each do |pkg_path|
+          resolved = File.expand_path(pkg_path, dir)
+          require resolved
+        end
+        config[:packages_loaded] = raw["packages"]
+      end
+
+      if raw["options"].is_a?(Hash)
+        config[:options] = raw["options"].each_with_object({}) do |(k, v), memo|
+          memo[k.to_s.tr("-", "_").to_sym] = v
+        end
+      end
+
+      config
+    rescue JSON::ParserError => e
+      warn "WARNING: Failed to parse #{path}: #{e.message}"
+      {}
+    end
+  end
+end

data/lib/mjml-rb/renderer.rb

@@ -113,6 +113,7 @@ module MjmlRb
 
     def build_html_document(content, context)
       content = minify_outlook_conditionals(content)
+      content = apply_html_attributes_to_content(content, context)
       title = context[:title].to_s
       preview = context[:preview]
       head_raw = Array(context[:head_raw]).join("\n")
@@ -165,7 +166,6 @@ module MjmlRb
         </html>
       HTML
 
-      html = apply_html_attributes(html, context)
       html = apply_inline_styles(html, context)
       html = merge_outlook_conditionals(html)
       before_doctype.empty? ? html : "#{before_doctype}\n#{html}"
@@ -307,23 +307,33 @@ module MjmlRb
       end
     end
 
-    def apply_html_attributes(html, context)
+    def apply_html_attributes_to_content(content, context)
       rules = context[:html_attributes] || {}
-      return html if rules.empty?
+      return content if rules.empty?
 
-      document = Nokogiri::HTML(html)
+      root = html_attributes_fragment_root(content, context)
 
       rules.each do |selector, attrs|
         next if selector.empty? || attrs.empty?
 
-        select_nodes(document, selector).each do |node|
+        select_nodes(root, selector).each do |node|
           attrs.each do |name, value|
             node[name] = value.to_s
           end
         end
       end
 
-      document.to_html
+      root.inner_html
+    end
+
+    def html_attributes_fragment_root(content, context)
+      wrapper_attrs = {
+        "data-mjml-body-root" => "true",
+        "lang" => context[:lang],
+        "dir" => context[:dir]
+      }
+      fragment = Nokogiri::HTML::DocumentFragment.parse("<div#{html_attrs(wrapper_attrs)}>#{content}</div>")
+      fragment.at_css("div[data-mjml-body-root='true']")
     end
 
     def apply_inline_styles(html, context)
@@ -638,6 +648,11 @@ module MjmlRb
         register_component(registry, Components::Section.new(self))
         register_component(registry, Components::Column.new(self))
         register_component(registry, Components::Spacer.new(self))
+
+        MjmlRb.component_registry.custom_components.each do |klass|
+          register_component(registry, klass.new(self))
+        end
+
         registry
       end
     end

data/lib/mjml-rb/validator.rb

@@ -49,7 +49,7 @@ module MjmlRb
       validate_supported_attributes(node, errors)
       validate_attribute_types(node, errors)
 
-      return if Dependencies::ENDING_TAGS.include?(node.tag_name)
+      return if MjmlRb.component_registry.ending_tags.include?(node.tag_name)
 
       node.element_children.each { |child| walk(child, errors) }
     end
@@ -66,9 +66,9 @@ module MjmlRb
     def validate_allowed_children(node, errors)
       # Ending-tag components treat content as raw HTML; REXML still parses
       # children structurally, so skip child validation for those tags.
-      return if Dependencies::ENDING_TAGS.include?(node.tag_name)
+      return if MjmlRb.component_registry.ending_tags.include?(node.tag_name)
 
-      allowed = Dependencies::RULES[node.tag_name]
+      allowed = MjmlRb.component_registry.dependency_rules[node.tag_name]
       return unless allowed
 
       node.element_children.each do |child|
@@ -134,12 +134,7 @@ module MjmlRb
     end
 
     def component_class_for_tag(tag_name)
-      MjmlRb::Components.constants.filter_map do |name|
-        value = MjmlRb::Components.const_get(name)
-        value if value.is_a?(Class) && value < MjmlRb::Components::Base
-      rescue NameError
-        nil
-      end.find { |klass| klass.tags.include?(tag_name) }
+      MjmlRb.component_registry.component_class_for_tag(tag_name)
     end
 
     def known_tag?(tag_name)

data/lib/mjml-rb/version.rb

@@ -1,3 +1,3 @@
 module MjmlRb
-  VERSION = "0.3.0".freeze
+  VERSION = "0.3.2".freeze
 end

data/lib/mjml-rb.rb

@@ -2,6 +2,8 @@ require_relative "mjml-rb/version"
 require_relative "mjml-rb/result"
 require_relative "mjml-rb/ast_node"
 require_relative "mjml-rb/dependencies"
+require_relative "mjml-rb/component_registry"
+require_relative "mjml-rb/config_file"
 require_relative "mjml-rb/parser"
 require_relative "mjml-rb/renderer"
 require_relative "mjml-rb/compiler"
@@ -43,6 +45,14 @@ module MjmlRb
       ActionView::Template.register_template_handler(:mjml, TemplateHandler.new)
     end
 
+    def register_component(klass, dependencies: {}, ending_tags: [])
+      component_registry.register(klass, dependencies: dependencies, ending_tags: ending_tags)
+    end
+
+    def component_registry
+      @component_registry ||= ComponentRegistry.new
+    end
+
     def mjml2html(mjml, options = {})
       Compiler.new(options).compile(mjml).to_h
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mjml-rb
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Andrei Andriichuk
@@ -53,6 +53,7 @@ files:
 - lib/mjml-rb/ast_node.rb
 - lib/mjml-rb/cli.rb
 - lib/mjml-rb/compiler.rb
+- lib/mjml-rb/component_registry.rb
 - lib/mjml-rb/components/accordion.rb
 - lib/mjml-rb/components/attributes.rb
 - lib/mjml-rb/components/base.rb
@@ -75,6 +76,7 @@ files:
 - lib/mjml-rb/components/spacer.rb
 - lib/mjml-rb/components/table.rb
 - lib/mjml-rb/components/text.rb
+- lib/mjml-rb/config_file.rb
 - lib/mjml-rb/dependencies.rb
 - lib/mjml-rb/parser.rb
 - lib/mjml-rb/railtie.rb