emjay 0.1.0

data/lib/emjay/renderer.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+require_relative "global_data"
+require_relative "registry"
+require_relative "skeleton"
+require_relative "helpers/merge_outlook_conditionals"
+require_relative "helpers/minify_outlook_conditionals"
+
+module Emjay
+  module Renderer
+    # HTML void elements that need self-closing conversion for XML parsing.
+    VOID_ELEMENTS_RE = /(<(?:br|hr|img|input|meta|link|area|base|col|embed|param|source|track|wbr)(?:\s[^>]*)?)>/i
+
+    def self.call(mjml_string, options = {})
+      # 1. Pre-process and parse MJML string with Nokogiri::XML.
+      # Two fixups are needed to bridge MJML (which embeds HTML content) and XML:
+      #   a) Convert HTML void elements to self-closing (e.g. <br> → <br/>)
+      #      so XML parsing doesn't treat them as unclosed tags
+      #   b) Escape bare < characters from template syntax in mj-raw
+      #      (e.g. { if item < 5 }) so they don't break XML parsing
+      preprocessed = mjml_string.gsub(VOID_ELEMENTS_RE, '\1/>')
+      preprocessed = preprocessed.gsub(/<(?![a-zA-Z\/!?])/, RAW_LT_PLACEHOLDER)
+      doc = Nokogiri::XML(preprocessed)
+      mjml_root = doc.at_xpath("//mjml") || doc.root
+
+      # 2. Build GlobalData
+      global_data = GlobalData.new(options)
+
+      # Extract lang/dir from root element
+      if mjml_root
+        owa = mjml_root["owa"]
+        global_data.force_owa_desktop = (owa == "desktop") if owa
+        global_data.lang = mjml_root["lang"] || "und"
+        global_data.dir = mjml_root["dir"] || "auto"
+      end
+
+      # 3. Find mj-head and mj-body
+      mj_head_el = mjml_root&.at_xpath("mj-head")
+      mj_body_el = mjml_root&.at_xpath("mj-body")
+
+      # Convert Nokogiri elements to our internal data structures (matching JS parsed format)
+      components = Registry.components
+
+      # Processing function (matches JS processing)
+      apply_attributes = method(:apply_attributes_fn).curry[global_data]
+
+      processing = lambda { |node, ctx|
+        return unless node
+        node = apply_attributes.call(node) if node.is_a?(Hash)
+
+        component_class = ctx[:components]&.[](node[:tag_name])
+        return unless component_class
+
+        component = component_class.new(
+          attributes: node[:attributes] || {},
+          children: node[:children] || [],
+          content: node[:content] || "",
+          context: ctx,
+          global_attributes: node[:global_attributes] || {},
+          raw_attrs: node[:raw_attrs] || {}
+        )
+
+        if component.respond_to?(:handler)
+          return component.handler
+        end
+
+        if component.respond_to?(:render)
+          component.render
+        end
+      }
+
+      # Head helpers context
+      head_helpers = {
+        components: components,
+        global_data: global_data,
+        add: ->(attr, *params) { global_data.add(attr, *params) }
+      }
+
+      # Process head
+      if mj_head_el
+        head_node = nokogiri_to_hash(mj_head_el)
+        head_result = processing.call(head_node, head_helpers)
+        global_data.head_raw = head_result if head_result.is_a?(Array)
+      end
+
+      # Body helpers context
+      body_helpers = {
+        components: components,
+        global_data: global_data,
+        container_width: "600px",
+        add_media_query: ->(class_name, data) {
+          pw = data[:parsed_width]
+          pw = pw.to_i if pw == pw.to_i
+          global_data.media_queries[class_name] =
+            "{ width:#{pw}#{data[:unit]} !important; max-width: #{pw}#{data[:unit]}; }"
+        },
+        add_head_style: ->(identifier, head_style_fn) {
+          global_data.head_style[identifier] = head_style_fn
+        },
+        add_component_head_style: ->(head_style_fn) {
+          global_data.components_head_style << head_style_fn
+        },
+        processing: ->(node, ctx) {
+          node = apply_attributes.call(node) if node.is_a?(Hash)
+          processing.call(node, ctx)
+        }
+      }
+
+      # Process body
+      content = nil
+      if mj_body_el
+        body_node = nokogiri_to_hash(mj_body_el)
+        body_node = apply_attributes.call(body_node)
+        content = processing.call(body_node, body_helpers)
+      end
+
+      raise "Malformed MJML. Check that your structure is correct and enclosed in <mjml> tags." unless content
+
+      # Minify outlook conditionals
+      content = MinifyOutlookConditionals.call(content)
+
+      # Handle mj-raw outside body (before-doctype)
+      mjml_root&.xpath("mj-raw")&.each do |raw_el|
+        if raw_el["position"] == "file-start"
+          global_data.before_doctype += raw_el.inner_html.gsub(RAW_LT_PLACEHOLDER, "<")
+        end
+      end
+
+      # Apply html_attributes via Nokogiri CSS selectors.
+      # Use XML fragment for parsing (preserves table structure, unlike HTML5
+      # which foster-parents text out of tables). Protect bare < from template
+      # syntax (mj-raw) with placeholders so XML parsing succeeds. Use custom
+      # serializer so text nodes (including > in templates) pass through raw.
+      unless global_data.html_attributes.empty?
+        escaped = content.gsub(/<(?![a-zA-Z\/!?])/, RAW_LT_PLACEHOLDER)
+        content_doc = Nokogiri::XML.fragment(escaped)
+        global_data.html_attributes.each do |selector, data|
+          content_doc.css(selector).each do |node|
+            data.each do |attr_name, value|
+              node[attr_name] = value || ""
+            end
+          end
+        end
+        content = serialize_fragment(content_doc).gsub(RAW_LT_PLACEHOLDER, "<")
+      end
+
+      # Wrap in skeleton
+      content = Skeleton.call(
+        before_doctype: global_data.before_doctype,
+        breakpoint: global_data.breakpoint,
+        content: content,
+        fonts: global_data.fonts,
+        media_queries: global_data.media_queries,
+        head_style: global_data.head_style,
+        components_head_style: global_data.components_head_style,
+        head_raw: global_data.head_raw.is_a?(Array) ? global_data.head_raw : [],
+        title: global_data.title,
+        style: global_data.style,
+        force_owa_desktop: global_data.force_owa_desktop,
+        printer_support: options[:printer_support] || false,
+        inline_style: global_data.inline_style,
+        lang: global_data.lang,
+        dir: global_data.dir
+      )
+
+      # CSS inlining for <mj-style inline="inline">
+      if global_data.inline_style.any?
+        content = inline_css(content, global_data.inline_style.join("\n"))
+      end
+
+      # Merge outlook conditionals
+      MergeOutlookConditionals.call(content)
+    end
+
+    # Converts a Nokogiri element to a hash matching the JS parsed format
+    def self.nokogiri_to_hash(element)
+      return nil unless element
+
+      attrs = {}
+      element.attributes.each { |name, attr| attrs[name] = attr.value }
+
+      children = element.children.select(&:element?).map { |child| nokogiri_to_hash(child) }
+
+      # For ending-tag components, content is the inner HTML
+      tag_name = element.name
+      component_class = Registry.find(tag_name)
+      content = if component_class&.ending_tag?
+        inner = element.inner_html.strip
+        # Restore escaped bare < characters (from template syntax in mj-raw etc.)
+        inner.gsub(RAW_LT_PLACEHOLDER, "<")
+      else
+        element.children.select(&:text?).map(&:text).join.strip
+      end
+
+      {
+        tag_name: tag_name,
+        attributes: attrs,
+        children: children,
+        content: content
+      }
+    end
+
+    # Port of the JS applyAttributes function — merges global defaults, classes, etc.
+    def self.apply_attributes_fn(global_data, node, parent_mj_class = "")
+      return node unless node.is_a?(Hash)
+
+      attrs = node[:attributes] || {}
+      tag_name = node[:tag_name]
+
+      # Resolve mj-class
+      classes = (attrs["mj-class"] || "").split(" ")
+      attributes_classes = classes.each_with_object({}) do |cls, acc|
+        mj_class_values = global_data.classes[cls] || {}
+        if acc["css-class"] && mj_class_values["css-class"]
+          acc.merge!(mj_class_values)
+          acc["css-class"] = "#{acc["css-class"]} #{mj_class_values["css-class"]}"
+        else
+          acc.merge!(mj_class_values)
+        end
+      end
+
+      # Default attributes for parent mj-class
+      default_attrs_for_classes = parent_mj_class.split(" ").each_with_object({}) do |cls, acc|
+        class_defaults = global_data.classes_default.dig(cls, tag_name)
+        acc.merge!(class_defaults) if class_defaults
+      end
+
+      next_parent_mj_class = attrs["mj-class"] || parent_mj_class
+
+      # Merge: global defaults -> class attrs -> class default attrs -> element attrs (minus mj-class)
+      element_attrs = attrs.except("mj-class")
+      merged_attrs = (global_data.default_attributes[tag_name] || {})
+        .merge(attributes_classes)
+        .merge(default_attrs_for_classes)
+        .merge(element_attrs)
+
+      # Recurse into children
+      merged_children = (node[:children] || []).map { |child|
+        apply_attributes_fn(global_data, child, next_parent_mj_class)
+      }
+
+      node.merge(
+        attributes: merged_attrs,
+        raw_attrs: element_attrs,
+        global_attributes: global_data.default_attributes["mj-all"] || {},
+        children: merged_children
+      )
+    end
+
+    # Inlines extra CSS rules into element style attributes using premailer.
+    # Mirrors the JS behavior: only the extra CSS (from <mj-style inline="inline">)
+    # is inlined; existing <style> tags in the document are preserved as-is.
+    def self.inline_css(html, extra_css)
+      require "premailer"
+
+      premailer = Premailer.new(
+        html,
+        with_html_string: true,
+        css_string: extra_css,
+        include_style_tags: false,
+        include_link_tags: false,
+        preserve_styles: true,
+        adapter: :nokogiri
+      )
+      premailer.to_inline_css
+    end
+
+    RAW_LT_PLACEHOLDER = "___MJML_RAW_LT___"
+    VOID_ELEMENTS = %w[area base br col embed hr img input link meta param source track wbr].freeze
+
+    # Custom serializer that preserves raw text content (no entity encoding
+    # for >, <, etc. in text nodes). Needed because mj-raw injects template
+    # syntax like { if item < 5 } that must pass through literally.
+    def self.serialize_fragment(node)
+      node.children.map { |c| serialize_node(c) }.join
+    end
+
+    def self.serialize_node(node)
+      if node.text?
+        node.text
+      elsif node.comment?
+        "<!--#{node.content}-->"
+      elsif node.element?
+        attrs = node.attributes.values.map { |a|
+          val = a.value.gsub("&", "&amp;").gsub('"', "&quot;")
+          " #{a.name}=\"#{val}\""
+        }.join
+        if VOID_ELEMENTS.include?(node.name) && node.children.empty?
+          "<#{node.name}#{attrs}>"
+        else
+          "<#{node.name}#{attrs}>#{serialize_fragment(node)}</#{node.name}>"
+        end
+      else
+        node.to_html
+      end
+    end
+
+    private_class_method :nokogiri_to_hash, :apply_attributes_fn, :inline_css,
+      :serialize_fragment, :serialize_node
+  end
+end

data/lib/emjay/skeleton.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "helpers/fonts"
+require_relative "helpers/media_queries"
+require_relative "helpers/styles"
+
+module Emjay
+  module Skeleton
+    # Builds the full HTML document skeleton. Port of skeleton.js.
+    def self.call(options)
+      before_doctype = options[:before_doctype] || ""
+      breakpoint = options[:breakpoint] || "480px"
+      content = options[:content] || ""
+      fonts = options[:fonts] || {}
+      media_queries = options[:media_queries] || {}
+      head_style = options[:head_style] || {}
+      components_head_style = options[:components_head_style] || []
+      head_raw = options[:head_raw] || []
+      title = options[:title] || ""
+      style = options[:style] || []
+      force_owa_desktop = options[:force_owa_desktop] || false
+      printer_support = options[:printer_support] || false
+      inline_style = options[:inline_style] || []
+      lang = options[:lang] || "und"
+      dir = options[:dir] || "auto"
+
+      before_doctype_str = before_doctype.empty? ? "" : "#{before_doctype}\n"
+
+      fonts_tags = Fonts.build_tags(content, inline_style, fonts)
+      media_query_tags = MediaQueries.build_tags(breakpoint, media_queries,
+        force_owa_desktop: force_owa_desktop,
+        printer_support: printer_support)
+      component_styles = Styles.build_from_components(breakpoint, components_head_style, head_style)
+      tag_styles = Styles.build_from_tags(breakpoint, style)
+      raw = head_raw.compact.join("\n")
+
+      <<~HTML
+        #{before_doctype_str}<!doctype html>
+        <html lang="#{lang}" dir="#{dir}" xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
+          <head>
+            <title>#{title}</title>
+            <!--[if !mso]><!-->
+            <meta http-equiv="X-UA-Compatible" content="IE=edge">
+            <!--<![endif]-->
+            <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1">
+            <style type="text/css">
+              #outlook a { padding:0; }
+              body { margin:0;padding:0;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%; }
+              table, td { border-collapse:collapse;mso-table-lspace:0pt;mso-table-rspace:0pt; }
+              img { border:0;height:auto;line-height:100%; outline:none;text-decoration:none;-ms-interpolation-mode:bicubic; }
+              p { display:block;margin:13px 0; }
+            </style>
+            <!--[if mso]>
+            <noscript>
+            <xml>
+            <o:OfficeDocumentSettings>
+              <o:AllowPNG/>
+              <o:PixelsPerInch>96</o:PixelsPerInch>
+            </o:OfficeDocumentSettings>
+            </xml>
+            </noscript>
+            <![endif]-->
+            <!--[if lte mso 11]>
+            <style type="text/css">
+              .mj-outlook-group-fix { width:100% !important; }
+            </style>
+            <![endif]-->
+            #{fonts_tags}
+            #{media_query_tags}
+            #{component_styles}
+            #{tag_styles}
+            #{raw}
+          </head>
+          #{content}
+        </html>
+      HTML
+    end
+  end
+end

data/lib/emjay/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Emjay
+  VERSION = "0.1.0"
+end

data/lib/emjay.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "emjay/version"
+require_relative "emjay/registry"
+require_relative "emjay/component"
+require_relative "emjay/body_component"
+require_relative "emjay/head_component"
+require_relative "emjay/global_data"
+require_relative "emjay/renderer"
+require_relative "emjay/skeleton"
+
+# Helpers
+require_relative "emjay/helpers/shorthand_parser"
+require_relative "emjay/helpers/width_parser"
+require_relative "emjay/helpers/conditional_tag"
+require_relative "emjay/helpers/suffix_css_classes"
+require_relative "emjay/helpers/merge_outlook_conditionals"
+require_relative "emjay/helpers/minify_outlook_conditionals"
+require_relative "emjay/helpers/fonts"
+require_relative "emjay/helpers/media_queries"
+require_relative "emjay/helpers/styles"
+require_relative "emjay/helpers/make_lower_breakpoint"
+require_relative "emjay/helpers/gen_random_hex_string"
+
+# Head components
+require_relative "emjay/components/head/mj_head"
+require_relative "emjay/components/head/mj_attributes"
+require_relative "emjay/components/head/mj_style"
+require_relative "emjay/components/head/mj_font"
+require_relative "emjay/components/head/mj_title"
+require_relative "emjay/components/head/mj_preview"
+require_relative "emjay/components/head/mj_breakpoint"
+require_relative "emjay/components/head/mj_html_attributes"
+
+# Body components
+require_relative "emjay/components/body/mj_body"
+require_relative "emjay/components/body/mj_section"
+require_relative "emjay/components/body/mj_column"
+require_relative "emjay/components/body/mj_text"
+require_relative "emjay/components/body/mj_wrapper"
+require_relative "emjay/components/body/mj_group"
+require_relative "emjay/components/body/mj_image"
+require_relative "emjay/components/body/mj_button"
+require_relative "emjay/components/body/mj_divider"
+require_relative "emjay/components/body/mj_spacer"
+require_relative "emjay/components/body/mj_table"
+require_relative "emjay/components/body/mj_raw"
+require_relative "emjay/components/body/mj_hero"
+require_relative "emjay/components/body/mj_social"
+require_relative "emjay/components/body/mj_social_element"
+require_relative "emjay/components/body/mj_navbar"
+require_relative "emjay/components/body/mj_navbar_link"
+require_relative "emjay/components/body/mj_accordion"
+require_relative "emjay/components/body/mj_accordion_element"
+require_relative "emjay/components/body/mj_accordion_title"
+require_relative "emjay/components/body/mj_accordion_text"
+require_relative "emjay/components/body/mj_carousel"
+require_relative "emjay/components/body/mj_carousel_image"
+
+module Emjay
+  def self.to_html(mjml_string, options = {})
+    Renderer.call(mjml_string, options)
+  end
+end
+
+require "emjay/railtie" if defined?(Rails::Railtie)

data/llms.txt

@@ -0,0 +1,130 @@
+# emjay
+
+> Pure-Ruby MJML renderer. Converts MJML email markup to responsive HTML.
+
+emjay is a Ruby implementation of MJML (https://mjml.io). It takes an MJML string and returns a complete HTML email with responsive tables, Outlook conditionals, and inlined CSS. No Node.js or native extensions required.
+
+## API
+
+The core API is a single method:
+
+    Emjay.to_html(mjml_string) -> html_string
+
+## Rails integration
+
+emjay registers an ActionView template handler and an ActionMailer interceptor via a Railtie. No configuration needed — just add `gem "emjay"` to the Gemfile.
+
+### How it works
+
+The `.mjml` template handler is an ERB passthrough — it does not compile MJML itself. An ActionMailer interceptor (`Emjay::Rails::MailInterceptor`) detects `<mjml` in the message body after Rails has assembled the full render (template + layout), then compiles MJML → HTML in one pass. This architecture enables MJML layouts.
+
+### Template naming
+
+Templates use the `.html.mjml` extension:
+
+    app/views/user_mailer/welcome.html.mjml
+
+Rails resolves this as: `.mjml` selects the emjay handler, `.html` sets the output MIME type.
+
+### ERB is always available
+
+The handler chains through ERB. All ERB tags (`<%= %>`, `<% %>`, `<%# %>`) work inside `.mjml` templates. There is no separate `.mjml.erb` extension — ERB support is built in.
+
+Use ERB exactly as you would in any other Rails template:
+
+- Instance variables from the mailer action: `<%= @user.name %>`
+- Helpers: `<%= number_to_currency(@amount) %>`
+- Partials: `<%= render "shared/header" %>`
+- Conditionals: `<% if @user.premium? %> ... <% end %>`
+
+### Layouts
+
+MJML layouts work like regular Rails mailer layouts. The layout provides the `<mjml>` / `<mj-body>` wrapper, and `yield` receives the template's MJML content sections:
+
+    app/views/layouts/mailer.html.mjml   — wraps yield with <mjml><mj-body>...</mj-body></mjml>
+    app/views/user_mailer/welcome.html.mjml — contains only <mj-section> content
+
+Set the layout in your mailer: `layout "mailer"`
+
+### Partials
+
+MJML partials work with the standard `render` helper. Use `.html.mjml` extension for partials that contain MJML components:
+
+    app/views/shared/_header.html.mjml
+
+Render them as usual: `<%= render "shared/header" %>`
+
+### Follow host app conventions
+
+When writing MJML templates in a Rails app, follow the conventions of the host application:
+
+- Use the same helper methods, partial patterns, and i18n approach as other views
+- Use mailer previews (`ActionMailer::Preview`) to iterate on email design
+- Provide a plain text alternative (`welcome.text.erb`) alongside the MJML template for multipart emails
+- Keep mailer actions simple — set instance variables and call `mail()`
+
+## MJML components
+
+MJML templates are XML documents wrapped in `<mjml>` tags. The full component reference is at https://documentation.mjml.io/
+
+### Structure
+
+Every MJML email follows this structure:
+
+    <mjml>
+      <mj-head>
+        <!-- head components: styles, fonts, attributes, title, preview -->
+      </mj-head>
+      <mj-body>
+        <mj-section>
+          <mj-column>
+            <!-- content components: text, image, button, etc. -->
+          </mj-column>
+        </mj-section>
+      </mj-body>
+    </mjml>
+
+Content must be nested inside `mj-section > mj-column`. Sections are full-width rows, columns divide them horizontally.
+
+### Head components
+
+- `mj-attributes` — set default attributes for components globally or by class
+- `mj-style` — add CSS to the `<head>` (use `inline="inline"` to inline into elements)
+- `mj-font` — register web fonts
+- `mj-title` — set the `<title>` tag
+- `mj-preview` — set preview text shown in inbox listings
+- `mj-breakpoint` — set the responsive breakpoint (default 480px)
+- `mj-html-attributes` — add HTML attributes to rendered elements via CSS selectors
+
+### Body components
+
+- `mj-section` — full-width row container
+- `mj-column` — vertical subdivision of a section
+- `mj-group` — non-responsive column grouping
+- `mj-wrapper` — wraps multiple sections with shared background
+- `mj-text` — text content (supports inline HTML)
+- `mj-image` — responsive image
+- `mj-button` — call-to-action button
+- `mj-divider` — horizontal rule
+- `mj-spacer` — vertical spacing
+- `mj-table` — HTML table passthrough
+- `mj-raw` — raw HTML passthrough
+- `mj-hero` — hero section with background image
+- `mj-social` / `mj-social-element` — social media icon links
+- `mj-navbar` / `mj-navbar-link` — horizontal navigation
+- `mj-accordion` / `mj-accordion-element` — expandable content
+- `mj-carousel` / `mj-carousel-image` — image carousel
+
+### Common attributes
+
+Most body components accept: `padding`, `background-color`, `css-class`, `mj-class`, `width`, `font-family`, `font-size`, `color`, `align`.
+
+Refer to the MJML documentation for the full attribute list per component: https://documentation.mjml.io/
+
+## Tips for generating MJML
+
+- Always wrap content in the `mj-section > mj-column` structure
+- Use `mj-attributes` to set shared styles instead of repeating attributes
+- Use `mj-style` with `inline="inline"` for CSS properties not available as component attributes
+- Use `mj-raw` sparingly — only for HTML that MJML components cannot express
+- Test with real email clients or use mailer previews — email rendering varies wildly across clients