mjml-rb 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5afc17046611848190458b50e1b7d0670011e8f1e32a6723b63c7e7ff76029c
-  data.tar.gz: ff832c4861cd1c28d76f47e0f66f257e8fa1c956dd6e0836826df83be3e4782d
+  metadata.gz: 99c98b34eee9aea7822dc4f59250b3b8ca008b98a17cd7e5063eb04595460c31
+  data.tar.gz: 6541eb2234e61dd3399dce72b6f0f45f4e810601ecf1c7ff2ccc9a6405d74b84
 SHA512:
-  metadata.gz: e43bae28df235a80ad028bc43e37401c45c59c8e0d486f09e8d22faa786c1e18e62e696bde4cce668fcee4ea1c7d3d037cec3ec93d890b0e8e33404f98b776fe
-  data.tar.gz: c35f403ee71148fa10f6e9d794a61695f35f74201e561fba1afecb4686c71388c01f13bf69c19b799214102ad142a6f86281d922b3ed5eed2ed1e348b446f737
+  metadata.gz: 3ae18240675e7e9bf5572634a09cb2ae1079e93c874088b917181245a8b20947f59368b07d911fc781cd96676a7953e9f2aaa650bf69ed7eae9e4e5ff2962782
+  data.tar.gz: d6ae46c90053abdfeeb2445c87c7ebc07fbd9e36ac47b335577b03d2bfa0debb2dd5c6f9ce9208910c338ae7e7798d29b0c98ed4fc2b9a8b2aaf9eedd045a2f4

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/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

@@ -1,5 +1,6 @@
 require "cgi"
 require "nokogiri"
+require "set"
 require_relative "components/accordion"
 require_relative "components/attributes"
 require_relative "components/body"
@@ -539,6 +540,7 @@ module MjmlRb
         existing[property] = merged
       end
       normalize_background_fallbacks!(node, existing)
+      sync_html_attributes!(node, existing)
       node["style"] = serialize_css_declarations(existing)
     end
 
@@ -552,12 +554,59 @@ module MjmlRb
           important: declarations.fetch("background-color", {}).fetch(:important, false)
         }
       end
+    end
+
+    # Sync HTML attributes from inlined CSS declarations.
+    # Mirrors Juice's attribute syncing: width/height on TABLE/TD/TH/IMG,
+    # and style-to-attribute mappings (bgcolor, background, align, valign)
+    # on table-related elements.
+    # See: https://github.com/Automattic/juice/blob/master/lib/inline.js
+    WIDTH_HEIGHT_ELEMENTS = Set.new(%w[table td th img]).freeze
+    TABLE_ELEMENTS = Set.new(%w[table th tr td caption colgroup col thead tbody tfoot]).freeze
+    STYLE_TO_ATTRIBUTE = {
+      "background-color" => "bgcolor",
+      "background-image" => "background",
+      "text-align" => "align",
+      "vertical-align" => "valign"
+    }.freeze
+
+    def sync_html_attributes!(node, declarations)
+      tag = node.name.downcase
 
-      return unless node.name == "td"
-      return unless node["bgcolor"]
-      return if %w[none transparent].include?(background_color.downcase)
+      # Sync width/height on TABLE, TD, TH, IMG
+      if WIDTH_HEIGHT_ELEMENTS.include?(tag)
+        %w[width height].each do |prop|
+          css_value = declaration_value(declarations[prop])
+          next if css_value.nil? || css_value.empty?
+
+          # Convert CSS px values to plain numbers for HTML attributes;
+          # keep other values (auto, %) as-is.
+          html_value = css_value.sub(/px\z/i, "")
+          node[prop] = html_value
+        end
+      end
 
-      node["bgcolor"] = background_color
+      # Sync style-to-attribute mappings on table elements
+      if TABLE_ELEMENTS.include?(tag)
+        STYLE_TO_ATTRIBUTE.each do |css_prop, html_attr|
+          css_value = declaration_value(declarations[css_prop])
+          next if css_value.nil? || css_value.empty?
+
+          case html_attr
+          when "bgcolor"
+            next if %w[none transparent].include?(css_value.downcase)
+            node[html_attr] = css_value
+          when "background"
+            # Extract url(...) from background-image
+            url = css_value[/url\(['"]?([^'")]+)['"]?\)/i, 1]
+            node[html_attr] = url if url
+          when "align"
+            node[html_attr] = css_value
+          when "valign"
+            node[html_attr] = css_value
+          end
+        end
+      end
     end
 
     def syncable_background?(value)
@@ -648,6 +697,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.1".freeze
+  VERSION = "0.3.3".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.1
+  version: 0.3.3
 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