emjay 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1eadb92be994c929ee0f5a480b38ea56de397a2cf6591c3c178e36960c47dbab
+  data.tar.gz: 3dc92597d64b1166a9b5301b0eadf88d0078dc47affa308d57c3ac9ce18d2b10
+SHA512:
+  metadata.gz: 820dd2348232379489964907f0e29c7ab679a3d3bf450bd9242c815efdc0d56102993894b2ecdf9ad08ec7f3a8d870ce1b9d916b73f8b363217c7ad4bcdd57cd
+  data.tar.gz: 6105020243889ce2517b3b786bfd50607cccda2a7fdecfb3515f58ca61560cae1608b35ff03c36ce74ba172142d3ea46791c59b56cce3ace716c324d0c5df12c

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julik Tarkhanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,158 @@
+# emjay
+
+A pure-Ruby implementation of [MJML](https://mjml.io), the email markup language. Converts MJML templates to responsive HTML emails — no Node.js, no native extensions, no shelling out.
+
+## Feature parity with MJML
+
+emjay implements the full set of standard MJML components:
+
+**Head components:** `mj-head`, `mj-attributes`, `mj-style` (including `inline`), `mj-font`, `mj-title`, `mj-preview`, `mj-breakpoint`, `mj-html-attributes`
+
+**Body components:** `mj-body`, `mj-section`, `mj-wrapper`, `mj-column`, `mj-group`, `mj-text`, `mj-image`, `mj-button`, `mj-divider`, `mj-spacer`, `mj-table`, `mj-raw`, `mj-hero`, `mj-social` / `mj-social-element`, `mj-navbar` / `mj-navbar-link`, `mj-accordion` / `mj-accordion-element` / `mj-accordion-title` / `mj-accordion-text`, `mj-carousel` / `mj-carousel-image`
+
+**Features:** CSS inlining via `<mj-style inline="inline">`, global default attributes, `mj-class`, `mj-html-attributes` with CSS selectors, custom fonts, responsive breakpoints, Outlook conditionals, `lang`/`dir` attributes.
+
+All components and features from the [MJML documentation](https://documentation.mjml.io/) should work as described. The [MJML templates and examples](https://mjml.io/templates) are a good starting point for building your own emails. Output is tested against the upstream [MJML 4 JavaScript implementation](https://github.com/mjmlio/mjml) using fixture-based comparison and backported behavioral tests. If you find a case where emjay produces different output from the reference MJML implementation, please [open an issue](https://github.com/julik/emjay/issues).
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "emjay"
+```
+
+Runtime dependencies: `nokogiri` for XML/HTML parsing, `premailer` for CSS inlining (`<mj-style inline="inline">`).
+
+## Usage
+
+### Standalone
+
+```ruby
+require "emjay"
+
+mjml = <<~MJML
+  <mjml>
+    <mj-body>
+      <mj-section>
+        <mj-column>
+          <mj-text>Hello World</mj-text>
+        </mj-column>
+      </mj-section>
+    </mj-body>
+  </mjml>
+MJML
+
+html = Emjay.to_html(mjml)
+```
+
+### Rails
+
+emjay includes a Railtie that registers an ActionView template handler automatically. Create templates with the `.html.mjml` extension:
+
+```
+app/views/user_mailer/welcome.html.mjml
+```
+
+ERB tags work inside `.mjml` templates — the handler always chains through ERB before compiling MJML:
+
+```erb
+<mjml>
+  <mj-body>
+    <mj-section>
+      <mj-column>
+        <mj-text>Welcome, <%= @user.name %>!</mj-text>
+      </mj-column>
+    </mj-section>
+  </mj-body>
+</mjml>
+```
+
+Your mailer needs no special setup:
+
+```ruby
+class UserMailer < ApplicationMailer
+  def welcome(user)
+    @user = user
+    mail(to: @user.email)
+  end
+end
+```
+
+Rails resolves the template automatically: `.mjml` selects the handler, `.html` sets the MIME type. If you also provide `welcome.text.erb`, ActionMailer sends a multipart email with both HTML and plain text parts.
+
+### Layouts
+
+MJML layouts work just like regular Rails mailer layouts. Create a layout that wraps `yield` with the MJML boilerplate:
+
+```erb
+<%# app/views/layouts/mailer.html.mjml %>
+<mjml>
+  <mj-head>
+    <mj-attributes>
+      <mj-all font-family="Helvetica, Arial, sans-serif" />
+    </mj-attributes>
+  </mj-head>
+  <mj-body>
+    <%= yield %>
+  </mj-body>
+</mjml>
+```
+
+Then your templates contain only the content sections:
+
+```erb
+<%# app/views/user_mailer/welcome.html.mjml %>
+<mj-section>
+  <mj-column>
+    <mj-text>Welcome, <%= @user.name %>!</mj-text>
+  </mj-column>
+</mj-section>
+```
+
+Set the layout in your mailer as usual:
+
+```ruby
+class UserMailer < ApplicationMailer
+  layout "mailer"
+end
+```
+
+### Partials
+
+MJML partials work with the standard `render` helper. Use them to share common sections across emails:
+
+```erb
+<%# app/views/shared/_header.html.mjml %>
+<mj-section background-color="#f0f0f0">
+  <mj-column>
+    <mj-image src="<%= @logo_url %>" width="150px" />
+  </mj-column>
+</mj-section>
+```
+
+```erb
+<%# app/views/user_mailer/welcome.html.mjml %>
+<%= render "shared/header" %>
+<mj-section>
+  <mj-column>
+    <mj-text>Welcome!</mj-text>
+  </mj-column>
+</mj-section>
+```
+
+### How it works
+
+The `.mjml` template handler is an ERB passthrough — it does not compile MJML itself. Instead, an ActionMailer interceptor (`Emjay::Rails::MailInterceptor`) compiles the assembled MJML to HTML after Rails has applied layouts and partials. This means `yield` in a layout receives MJML (not HTML), and the full document is compiled in one pass.
+
+## Other Ruby MJML implementations
+
+- [mjml-rails](https://github.com/sighmon/mjml-rails) — Rails integration that shells out to the MJML Node.js binary. Requires Node.js at runtime.
+- [mjml-ruby](https://github.com/kolybasov/mjml-ruby) — Ruby wrapper around the MJML Node.js parser. Also requires Node.js.
+- [mrml-ruby](https://github.com/jdrouet/mrml/tree/main/packages/mrml-ruby) — Ruby bindings to [MRML](https://github.com/jdrouet/mrml), a Rust reimplementation of MJML. Requires a compiled native extension.
+
+emjay differs from all of the above by being pure Ruby — it has no dependency on Node.js or native extensions.
+
+## License
+
+MIT

data/lib/emjay/body_component.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require_relative "component"
+require_relative "helpers/shorthand_parser"
+require_relative "helpers/width_parser"
+
+module Emjay
+  # Base class for body components. Port of JS BodyComponent from createComponent.js.
+  class BodyComponent < Component
+    def get_styles
+      {}
+    end
+
+    # Converts a style hash (or style name string) to an inline CSS string.
+    # Supports dot-notation for nested style lookups (e.g., "carousel.div").
+    def styles(name_or_hash)
+      styles_object = if name_or_hash.is_a?(String)
+        if name_or_hash.include?(".")
+          parts = name_or_hash.split(".")
+          result = get_styles
+          parts.each { |part| result = result&.dig(part.to_sym) || result&.dig(part) }
+          result
+        else
+          get_styles[name_or_hash.to_sym] || get_styles[name_or_hash]
+        end
+      elsif name_or_hash.is_a?(Symbol)
+        get_styles[name_or_hash]
+      else
+        name_or_hash
+      end
+
+      return "" unless styles_object
+
+      styles_object.each_with_object(+"") do |(name, value), output|
+        output << "#{name}:#{value};" unless value.nil?
+      end
+    end
+
+    # Builds an HTML attribute string. The `style:` key auto-resolves through #styles.
+    def html_attributes(attrs)
+      attrs.each_with_object(+"") do |(name, value), output|
+        next if value.nil?
+        resolved = if name.to_s == "style"
+          styles(value)
+        else
+          value
+        end
+        output << " #{name}=\"#{resolved}\""
+      end
+    end
+
+    def get_shorthand_attr_value(attribute, direction)
+      dir_attr = get_attribute("#{attribute}-#{direction}")
+      return dir_attr.to_i if dir_attr
+
+      base_attr = get_attribute(attribute)
+      return 0 unless base_attr
+
+      ShorthandParser.call(base_attr, direction)
+    end
+
+    def get_shorthand_border_value(direction, attribute = "border")
+      border_direction = direction && get_attribute("#{attribute}-#{direction}")
+      border = get_attribute(attribute)
+      BorderParser.call(border_direction || border || "0")
+    end
+
+    def get_box_widths
+      container_width = @context[:container_width]
+      parsed_width = container_width.to_i
+
+      paddings = get_shorthand_attr_value("padding", "right") +
+        get_shorthand_attr_value("padding", "left")
+
+      borders = get_shorthand_border_value("right") +
+        get_shorthand_border_value("left")
+
+      {
+        total_width: parsed_width,
+        borders: borders,
+        paddings: paddings,
+        box: parsed_width - paddings - borders
+      }
+    end
+
+    def get_child_context
+      @context
+    end
+
+    # Renders child components. Supports renderer: lambda, attributes: merge, raw_xml: mode.
+    def render_children(children = nil, opts = {})
+      renderer = opts[:renderer] || ->(component) { component.render }
+      extra_attributes = opts[:attributes] || {}
+      extra_props = opts[:props] || {}
+
+      children = children || @props[:children] || []
+
+      sibling = children.length
+      components = @context[:components] || {}
+
+      raw_components = components.values.select { |c| c.raw_element? }
+      non_raw_siblings = children.count { |child|
+        !raw_components.any? { |c| c.component_name == child[:tag_name] }
+      }
+
+      output = +""
+      children.each_with_index do |child, index|
+        component_class = components[child[:tag_name]]
+        next unless component_class
+
+        child_data = {
+          attributes: extra_attributes.merge(child[:attributes] || {}),
+          children: child[:children] || [],
+          content: child[:content] || "",
+          context: get_child_context,
+          global_attributes: child[:global_attributes] || {},
+          raw_attrs: child[:raw_attrs] || {},
+          props: extra_props.merge(
+            first: index == 0,
+            index: index,
+            last: index + 1 == sibling,
+            sibling: sibling,
+            non_raw_siblings: non_raw_siblings
+          )
+        }
+
+        component = component_class.new(child_data)
+
+        if component.respond_to?(:head_style)
+          @context[:add_head_style]&.call(child[:tag_name], component.method(:head_style))
+        end
+        if component.respond_to?(:component_head_style)
+          @context[:add_component_head_style]&.call(component.method(:component_head_style))
+        end
+
+        output << renderer.call(component)
+      end
+
+      output
+    end
+  end
+end

data/lib/emjay/component.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Emjay
+  # Base class for all MJML components. Port of JS Component class from createComponent.js.
+  # Takes parsed node data (attributes, children, content) + context hash.
+  class Component
+    attr_reader :attributes, :props, :context
+
+    class << self
+      def component_name
+        raise NotImplementedError, "#{name} must define self.component_name"
+      end
+
+      def ending_tag?
+        false
+      end
+
+      def raw_element?
+        false
+      end
+
+      def default_attributes
+        {}
+      end
+
+      def allowed_attributes
+        {}
+      end
+    end
+
+    # initialDatas in JS: { attributes, children, content, context, props, globalAttributes, rawAttrs }
+    def initialize(initial_data = {})
+      attrs = initial_data[:attributes] || {}
+      @children = initial_data[:children] || []
+      @content = initial_data[:content] || ""
+      @context = initial_data[:context] || {}
+      @props = initial_data[:props] || {}
+      @props[:children] = @children
+      @props[:content] = @content
+      @props[:raw_attrs] = initial_data[:raw_attrs] || {}
+      global_attributes = initial_data[:global_attributes] || {}
+
+      # Attribute merging: defaults -> global -> element
+      @attributes = self.class.default_attributes
+        .merge(global_attributes)
+        .merge(attrs)
+    end
+
+    def get_child_context
+      @context
+    end
+
+    def get_attribute(name)
+      @attributes[name]
+    end
+
+    def get_content
+      (@content || "").strip
+    end
+  end
+end

data/lib/emjay/components/body/mj_accordion.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "../../body_component"
+require_relative "../../registry"
+
+module Emjay
+  module Components
+    class MjAccordion < BodyComponent
+      def self.component_name
+        "mj-accordion"
+      end
+
+      def self.default_attributes
+        {
+          "border" => "2px solid black",
+          "font-family" => "Ubuntu, Helvetica, Arial, sans-serif",
+          "icon-align" => "middle",
+          "icon-wrapped-url" => "https://i.imgur.com/bIXv1bk.png",
+          "icon-wrapped-alt" => "+",
+          "icon-unwrapped-url" => "https://i.imgur.com/w4uTygT.png",
+          "icon-unwrapped-alt" => "-",
+          "icon-position" => "right",
+          "icon-height" => "32px",
+          "icon-width" => "32px",
+          "padding" => "10px 25px"
+        }
+      end
+
+      def self.allowed_attributes
+        {
+          "container-background-color" => "color",
+          "border" => "string",
+          "font-family" => "string",
+          "icon-align" => "enum(top,middle,bottom)",
+          "icon-width" => "unit(px,%)",
+          "icon-height" => "unit(px,%)",
+          "icon-wrapped-url" => "string",
+          "icon-wrapped-alt" => "string",
+          "icon-unwrapped-url" => "string",
+          "icon-unwrapped-alt" => "string",
+          "icon-position" => "enum(left,right)",
+          "padding-bottom" => "unit(px,%)",
+          "padding-left" => "unit(px,%)",
+          "padding-right" => "unit(px,%)",
+          "padding-top" => "unit(px,%)",
+          "padding" => "unit(px,%){1,4}"
+        }
+      end
+
+      def head_style(_breakpoint = nil)
+        "\n      noinput.mj-accordion-checkbox { display:block!important; }\n\n      @media yahoo, only screen and (min-width:0) {\n        .mj-accordion-element { display:block; }\n        .mj-accordion-checkbox[type=\"checkbox\"], .mj-accordion-less { display:none!important; }\n        .mj-accordion-checkbox[type=\"checkbox\"] + * .mj-accordion-title { cursor:pointer; touch-action:manipulation; -webkit-user-select:none; -moz-user-select:none; user-select:none; }\n        .mj-accordion-checkbox[type=\"checkbox\"] + * .mj-accordion-content { overflow:hidden; display:none; }\n        .mj-accordion-checkbox[type=\"checkbox\"] + * .mj-accordion-more { display:block!important; }\n        .mj-accordion-checkbox:checked + * .mj-accordion-content { display:block; }\n        .mj-accordion-checkbox:checked + * .mj-accordion-more { display:none!important; }\n        .mj-accordion-checkbox:checked + * .mj-accordion-less { display:block!important; }\n      }\n\n      .moz-text-html input.mj-accordion-checkbox + * .mj-accordion-title { cursor: auto; touch-action: auto; -webkit-user-select: auto; -moz-user-select: auto; user-select: auto; }\n      .moz-text-html input.mj-accordion-checkbox + * .mj-accordion-content { overflow: hidden; display: block; }\n      .moz-text-html input.mj-accordion-checkbox + * .mj-accordion-ico { display: none; }\n\n      @goodbye { @gmail }\n    "
+      end
+
+      def get_styles
+        {
+          table: {
+            "width" => "100%",
+            "border-collapse" => "collapse",
+            "border" => get_attribute("border"),
+            "border-bottom" => "none",
+            "font-family" => get_attribute("font-family")
+          }
+        }
+      end
+
+      def get_child_context
+        @context.merge(accordionFontFamily: get_attribute("font-family"))
+      end
+
+      def render
+        children = @props[:children] || []
+
+        children_attr = %w[border icon-align icon-width icon-height icon-position
+          icon-wrapped-url icon-wrapped-alt icon-unwrapped-url icon-unwrapped-alt].each_with_object({}) do |attr, hash|
+          hash[attr] = get_attribute(attr)
+        end
+
+        table_attrs = html_attributes(
+          cellspacing: "0",
+          cellpadding: "0",
+          class: "mj-accordion",
+          style: :table
+        )
+
+        <<~HTML
+          <table
+            #{table_attrs}
+          >
+            <tbody>
+              #{render_children(children, attributes: children_attr)}
+            </tbody>
+          </table>
+        HTML
+      end
+    end
+  end
+
+  Registry.register(Components::MjAccordion)
+end

data/lib/emjay/components/body/mj_accordion_element.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative "../../body_component"
+require_relative "../../registry"
+require_relative "../../helpers/conditional_tag"
+
+module Emjay
+  module Components
+    class MjAccordionElement < BodyComponent
+      def self.component_name
+        "mj-accordion-element"
+      end
+
+      def self.default_attributes
+        {}
+      end
+
+      def self.allowed_attributes
+        {
+          "background-color" => "color",
+          "border" => "string",
+          "font-family" => "string",
+          "icon-align" => "enum(top,middle,bottom)",
+          "icon-width" => "unit(px,%)",
+          "icon-height" => "unit(px,%)",
+          "icon-wrapped-url" => "string",
+          "icon-wrapped-alt" => "string",
+          "icon-unwrapped-url" => "string",
+          "icon-unwrapped-alt" => "string",
+          "icon-position" => "enum(left,right)"
+        }
+      end
+
+      def get_styles
+        {
+          td: {
+            "padding" => "0px",
+            "background-color" => get_attribute("background-color")
+          },
+          label: {
+            "font-size" => "13px",
+            "font-family" => get_attribute("font-family")
+          },
+          input: {
+            "display" => "none"
+          }
+        }
+      end
+
+      def get_child_context
+        @context.merge(elementFontFamily: get_attribute("font-family"))
+      end
+
+      def render
+        tr_attrs = html_attributes(class: get_attribute("css-class"))
+        td_attrs = html_attributes(style: :td)
+        label_attrs = html_attributes(
+          class: "mj-accordion-element",
+          style: :label
+        )
+        input_attrs = html_attributes(
+          class: "mj-accordion-checkbox",
+          type: "checkbox",
+          style: :input
+        )
+
+        input_html = ConditionalTag.conditional_tag(
+          "<input#{input_attrs} />",
+          negation: true
+        )
+
+        <<~HTML
+          <tr
+            #{tr_attrs}
+          >
+            <td#{td_attrs}>
+              <label
+                #{label_attrs}
+              >
+                #{input_html}
+                <div>
+                  #{handle_missing_children}
+                </div>
+              </label>
+            </td>
+          </tr>
+        HTML
+      end
+
+      private
+
+      def handle_missing_children
+        children = @props[:children] || []
+        children_attr = %w[border icon-align icon-width icon-height icon-position
+          icon-wrapped-url icon-wrapped-alt icon-unwrapped-url icon-unwrapped-alt].each_with_object({}) do |attr, hash|
+          hash[attr] = get_attribute(attr)
+        end
+
+        result = []
+
+        has_title = children.any? { |c| c[:tag_name] == "mj-accordion-title" }
+        unless has_title
+          title_component = Components::MjAccordionTitle.new(
+            attributes: children_attr,
+            context: get_child_context
+          )
+          result << title_component.render
+        end
+
+        result << render_children(children, attributes: children_attr)
+
+        has_text = children.any? { |c| c[:tag_name] == "mj-accordion-text" }
+        unless has_text
+          text_component = Components::MjAccordionText.new(
+            attributes: children_attr,
+            context: get_child_context
+          )
+          result << text_component.render
+        end
+
+        result.join("\n")
+      end
+    end
+  end
+
+  Registry.register(Components::MjAccordionElement)
+end