activemail 1.0.0

data/lib/active_mail/components/inky.rb

@@ -0,0 +1,18 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ActiveMail
+  module Components
+    # Renders a bare <tr> (mirrors inky.js).
+    class Inky < Base
+      extend T::Sig
+
+      sig { override.params(_node: Nokogiri::XML::Node, inner: String).returns(String) }
+      def transform(_node, inner)
+        %(<tr>#{inner}</tr>)
+      end
+    end
+  end
+end

data/lib/active_mail/components/menu.rb

@@ -0,0 +1,22 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ActiveMail
+  module Components
+    class Menu < Base
+      extend T::Sig
+
+      sig { override.params(node: Nokogiri::XML::Node, inner: String).returns(String) }
+      def transform(node, inner)
+        attributes = combine_attributes(node, 'menu')
+        [
+          %(<table #{attributes} #{TABLE_RESET}#{style_attribute(node)}><tbody><tr><td>),
+          %(<table #{TABLE_RESET}><tbody><tr>#{inner}</tr></tbody></table>),
+          '</td></tr></tbody></table>'
+        ].join
+      end
+    end
+  end
+end

data/lib/active_mail/components/menu_item.rb

@@ -0,0 +1,21 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ActiveMail
+  module Components
+    class MenuItem < Base
+      extend T::Sig
+
+      sig { override.params(node: Nokogiri::XML::Node, inner: String).returns(String) }
+      def transform(node, inner)
+        attributes = combine_attributes(node, 'menu-item')
+        # No href → a non-link item, not a broken <a href="">; mirrors <button>.
+        content = node.attr('href') ? %(<a href="#{escape_attr(node.attr('href'))}"#{target_attribute(node)}>#{inner}</a>) : inner
+        th = ::ActiveMail::Core::INTERIM_TH_TAG
+        %(<#{th} #{attributes}#{style_attribute(node)}>#{content}</#{th}>)
+      end
+    end
+  end
+end

data/lib/active_mail/components/row.rb

@@ -0,0 +1,18 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ActiveMail
+  module Components
+    class Row < Base
+      extend T::Sig
+
+      sig { override.params(node: Nokogiri::XML::Node, inner: String).returns(String) }
+      def transform(node, inner)
+        attributes = combine_attributes(node, 'row')
+        %(<table #{attributes} #{TABLE_RESET}#{style_attribute(node, 'width:100%;')}><tbody><tr>#{inner}</tr></tbody></table>)
+      end
+    end
+  end
+end

data/lib/active_mail/components/spacer.rb

@@ -0,0 +1,45 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ActiveMail
+  module Components
+    class Spacer < Base
+      extend T::Sig
+
+      sig { override.params(node: Nokogiri::XML::Node, _inner: String).returns(String) }
+      def transform(node, _inner)
+        classes = combine_classes(node, 'spacer')
+        size_sm = node.attr('size-sm')
+        size_lg = node.attr('size-lg')
+
+        return build_table(node, classes, nil, size_for(node.attr('size'))) unless size_sm || size_lg
+
+        html = +''
+        html << build_table(node, classes, 'hide-for-large', size_for(size_sm)) if size_sm
+        html << build_table(node, classes, 'show-for-large', size_for(size_lg)) if size_lg
+        html
+      end
+
+      private
+
+      sig { params(value: T.untyped).returns(Integer) }
+      def size_for(value)
+        positive_int(value) || 16
+      end
+
+      sig { params(node: Nokogiri::XML::Node, classes: String, extra: T.nilable(String), size: Integer).returns(String) }
+      def build_table(node, classes, extra, size)
+        css_class = extra ? "#{classes} #{extra}" : classes
+        # mso-line-height-rule:exactly keeps Outlook from inflating the spacer.
+        style = "font-size:#{size}px;line-height:#{size}px;mso-line-height-rule:exactly;"
+        [
+          %(<table class="#{css_class}" #{TABLE_RESET}#{style_attribute(node, 'width:100%;')}><tbody><tr>),
+          %(<td height="#{size}" style="#{style}">&nbsp;</td>),
+          '</tr></tbody></table>'
+        ].join
+      end
+    end
+  end
+end

data/lib/active_mail/components/wrapper.rb

@@ -0,0 +1,21 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ActiveMail
+  module Components
+    class Wrapper < Base
+      extend T::Sig
+
+      sig { override.params(node: Nokogiri::XML::Node, inner: String).returns(String) }
+      def transform(node, inner)
+        attributes = combine_attributes(node, 'wrapper')
+        [
+          %(<table #{attributes} #{TABLE_RESET} align="center"#{style_attribute(node, 'width:100%;')}><tbody><tr>),
+          %(<td class="wrapper-inner">#{inner}</td></tr></tbody></table>)
+        ].join
+      end
+    end
+  end
+end

data/lib/active_mail/configuration.rb

@@ -0,0 +1,229 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+require_relative 'tokens'
+require_relative 'inliner/base'
+require_relative 'inliner/premailer'
+require_relative 'inliner/roadie'
+require_relative 'inliner/null'
+
+module ActiveMail
+  extend T::Sig
+
+  ComponentMap = T.type_alias { T::Hash[String, T.class_of(ActiveMail::Components::Base)] }
+
+  sig { returns(ActiveMail::Configuration) }
+  def self.configuration
+    @configuration ||= T.let(Configuration.new, T.nilable(ActiveMail::Configuration))
+  end
+
+  sig { returns(ActiveMail::Tokens) }
+  def self.tokens
+    configuration.tokens
+  end
+
+  sig { params(config: T.untyped).returns(ActiveMail::Configuration) }
+  def self.configuration=(config)
+    raise TypeError, 'Not an ActiveMail::Configuration' unless config.is_a?(Configuration)
+
+    @configuration = config
+  end
+
+  sig { params(block: T.proc.params(config: ActiveMail::Configuration).void).void }
+  def self.configure(&block)
+    block.call(configuration)
+  end
+
+  # Parse mode (and the Guard's same decision): a full document carries <html.
+  sig { params(html: String).returns(T::Boolean) }
+  def self.full_document?(html)
+    html.match?(/<html/i)
+  end
+
+  # The complete SCSS variable bridge — tokens + the container_width layout knob.
+  # Single source for the .scss.erb bridge (Sprockets) and tokens:export (Propshaft).
+  sig { returns(String) }
+  def self.scss_variables
+    "#{tokens.to_scss}$am-grid-container-width: #{configuration.container_width}px !default;\n"
+  end
+
+  # Route warnings to the app logger when present (Sentry breadcrumbs, log
+  # aggregation), else $stderr — which is often dropped in production.
+  sig { params(message: String).void }
+  def self.log_warning(message)
+    logger = rails_logger
+    logger ? logger.warn(message) : Kernel.warn(message)
+  end
+
+  sig { returns(T.untyped) }
+  def self.rails_logger
+    return unless Object.const_defined?(:Rails)
+
+    rails = Object.const_get(:Rails)
+    rails.respond_to?(:logger) ? rails.logger : nil
+  end
+
+  # Invalid bytes degrade deterministically to U+FFFD, but that silently corrupts
+  # content — surface it per on_parse_error before scrubbing.
+  sig { params(html_string: String).returns(String) }
+  def self.scrub_invalid_bytes(html_string)
+    mode = configuration.on_parse_error
+    message = '[activemail] input had invalid byte sequences; scrubbed to U+FFFD'
+    raise ParseError, message if mode == :raise
+
+    log_warning(message) unless mode == :ignore
+    html_string.scrub
+  end
+
+  # Zero or negative dimensions blow up at transform time (Infinity ghost width).
+  # Reject non-integers rather than silently coercing ("abc"→0, 12.9→12).
+  sig { params(name: Symbol, value: T.untyped).returns(Integer) }
+  def self.assert_positive_dimension!(name, value)
+    raise ArgumentError, "#{name} must be a positive integer, got #{value.inspect}" unless value.is_a?(Integer) && value.positive?
+
+    value
+  end
+
+  class Configuration
+    extend T::Sig
+
+    ON_PARSE_ERROR_MODES = T.let(%i[ignore warn raise].freeze, T::Array[Symbol])
+
+    INLINERS = T.let(
+      { premailer: ActiveMail::Inliner::Premailer, roadie: ActiveMail::Inliner::Roadie, null: ActiveMail::Inliner::Null }.freeze,
+      T::Hash[Symbol, T.class_of(ActiveMail::Inliner::Base)]
+    )
+
+    InlinerSetting = T.type_alias { T.any(Symbol, ActiveMail::Inliner::Base, T.class_of(ActiveMail::Inliner::Base)) }
+
+    sig { returns(InlinerSetting) }
+    attr_reader :inliner
+
+    # Lets a host already running another inliner (e.g. premailer-rails) opt out.
+    sig { returns(T::Boolean) }
+    attr_reader :register_inline_interceptor
+
+    sig { params(value: T.untyped).void }
+    def register_inline_interceptor=(value)
+      raise TypeError, 'register_inline_interceptor must be true or false' unless [true, false].include?(value)
+
+      @register_inline_interceptor = value
+    end
+
+    sig { returns(Symbol) }
+    attr_reader :template_engine
+
+    sig { returns(Symbol) }
+    attr_reader :on_parse_error
+
+    sig { returns(Integer) }
+    attr_reader :column_count
+
+    sig { returns(Integer) }
+    attr_reader :container_width
+
+    # Mutating the returned hash would bypass validate_component!.
+    sig { returns(ActiveMail::ComponentMap) }
+    def components
+      @components.dup.freeze
+    end
+
+    sig { returns(ActiveMail::Tokens) }
+    def tokens
+      @tokens ||= T.let(ActiveMail::Tokens.new, T.nilable(ActiveMail::Tokens))
+    end
+
+    sig { void }
+    def initialize
+      @template_engine = T.let(:erb, Symbol)
+      @column_count = T.let(12, Integer)
+      @container_width = T.let(600, Integer)
+      @components = T.let({}, ActiveMail::ComponentMap)
+      @on_parse_error = T.let(:warn, Symbol)
+      @tokens = T.let(nil, T.nilable(ActiveMail::Tokens))
+      @inliner = T.let(:premailer, InlinerSetting)
+      @resolved_inliner = T.let(nil, T.nilable(ActiveMail::Inliner::Base))
+      @register_inline_interceptor = T.let(true, T::Boolean)
+    end
+
+    # Validates eagerly (like sibling setters): a typo fails at boot, not silently mid-delivery.
+    sig { params(value: T.any(Symbol, String, ActiveMail::Inliner::Base, T.class_of(ActiveMail::Inliner::Base))).returns(InlinerSetting) }
+    def inliner=(value)
+      resolved = value.is_a?(String) ? value.to_sym : value
+      resolve_inliner(resolved) # raises on an invalid value, eagerly
+      @resolved_inliner = nil   # a new setting invalidates the memoized instance
+      @inliner = resolved
+    end
+
+    # Memoized so the lifecycle is consistent (one instance reused, not re-built per call).
+    sig { returns(ActiveMail::Inliner::Base) }
+    def resolved_inliner
+      @resolved_inliner ||= resolve_inliner(@inliner)
+    end
+
+    sig { params(value: T.untyped).returns(Symbol) }
+    def on_parse_error=(value)
+      mode = value.respond_to?(:to_sym) ? value.to_sym : value
+      raise ArgumentError, "on_parse_error must be one of #{ON_PARSE_ERROR_MODES.inspect}" unless ON_PARSE_ERROR_MODES.include?(mode)
+
+      @on_parse_error = mode
+    end
+
+    sig { params(value: T.untyped).returns(Symbol) }
+    def template_engine=(value)
+      raise TypeError, "#{value.inspect} (#{value.class}) does not respond to 'to_sym'" unless value.respond_to?(:to_sym)
+
+      @template_engine = value.to_sym
+    end
+
+    sig { params(value: T.untyped).returns(Integer) }
+    def column_count=(value)
+      @column_count = positive_integer!(:column_count, value)
+    end
+
+    sig { params(value: T.untyped).returns(Integer) }
+    def container_width=(value)
+      @container_width = positive_integer!(:container_width, value)
+    end
+
+    sig { params(value: T.untyped).returns(ActiveMail::ComponentMap) }
+    def components=(value)
+      raise TypeError, "#{value.inspect} (#{value.class}) does not respond to 'to_hash'" unless value.respond_to?(:to_hash)
+
+      # Lookup is by node name (String); a Symbol key would never match.
+      normalized = value.to_hash.transform_keys(&:to_s)
+      normalized.each { |tag, klass| ActiveMail::Components.validate_component!(tag, klass) }
+      @components = normalized
+    end
+
+    sig { params(tag: T.any(String, Symbol), component_class: T.class_of(ActiveMail::Components::Base)).void }
+    def register_component(tag, component_class)
+      ActiveMail::Components.validate_component!(tag, component_class)
+
+      @components = @components.merge(tag.to_s => component_class)
+    end
+
+    private
+
+    # Single source for both eager validation (in the setter) and resolution.
+    sig { params(value: InlinerSetting).returns(ActiveMail::Inliner::Base) }
+    def resolve_inliner(value)
+      return value if value.is_a?(ActiveMail::Inliner::Base)
+      return value.new if value.is_a?(Class) && value < ActiveMail::Inliner::Base
+      return T.must(INLINERS[value]).new if value.is_a?(Symbol) && INLINERS.key?(value)
+
+      raise ArgumentError, "unknown inliner #{value.inspect}, expected one of #{INLINERS.keys.inspect}, an Inliner::Base subclass, or an instance"
+    end
+
+    # Integer-only (no to_int): a Float would otherwise be silently truncated
+    # (12.9 -> 12), contradicting assert_positive_dimension!'s invariant.
+    sig { params(name: Symbol, value: T.untyped).returns(Integer) }
+    def positive_integer!(name, value)
+      raise TypeError, "#{name} must be an Integer, got #{value.inspect} (#{value.class})" unless value.is_a?(Integer)
+
+      ActiveMail.assert_positive_dimension!(name, value)
+    end
+  end
+end

data/lib/active_mail/inliner/base.rb

@@ -0,0 +1,29 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module ActiveMail
+  module Inliner
+    # Raised when an adapter fails; the original (premailer/roadie/nokogiri)
+    # exception is preserved as Exception#cause with its backtrace intact.
+    class Error < StandardError; end
+
+    # DIP seam: ActiveMail depends on this abstraction, not premailer/roadie.
+    class Base
+      extend T::Sig
+      extend T::Helpers
+
+      abstract!
+
+      sig { abstract.params(html: String).returns(String) }
+      def inline(html); end
+
+      # Lets the interceptor skip work without type-checking concrete adapters.
+      sig { returns(T::Boolean) }
+      def noop?
+        false
+      end
+    end
+  end
+end

data/lib/active_mail/inliner/interceptor.rb

@@ -0,0 +1,51 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module ActiveMail
+  module Inliner
+    class Interceptor
+      class << self
+        extend T::Sig
+
+        sig { params(message: T.untyped).void }
+        def delivering_email(message)
+          config = ActiveMail.configuration
+          # Runtime check: an engine initializer runs before the host's, so a
+          # boot-time flag read would always see the default.
+          return unless config.register_inline_interceptor
+
+          inliner = config.resolved_inliner
+          return if inliner.noop?
+
+          html_parts(message).each do |part|
+            part.body = inliner.inline(part.body.to_s)
+          rescue StandardError => e
+            # Surface which inliner failed; do not swallow (a silently non-inlined
+            # mail is worse). Ruby sets e as #cause, preserving the original backtrace.
+            raise ActiveMail::Inliner::Error, "[#{inliner.class}] CSS inlining failed: #{e.message}"
+          end
+        end
+
+        private
+
+        # The html part(s) to inline: a single text/html message, or every text/html
+        # part of a multipart message. Attachments are never inlined.
+        sig { params(message: T.untyped).returns(T::Array[T.untyped]) }
+        def html_parts(message)
+          return message.all_parts.select { |part| html_body_part?(part) } if message.multipart?
+
+          html_body_part?(message) ? [message] : []
+        end
+
+        sig { params(part: T.untyped).returns(T::Boolean) }
+        def html_body_part?(part)
+          return false unless part.respond_to?(:mime_type) && part.mime_type == 'text/html'
+
+          !(part.respond_to?(:attachment?) && part.attachment?)
+        end
+      end
+    end
+  end
+end

data/lib/active_mail/inliner/null.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ActiveMail
+  module Inliner
+    # Opt-out / test adapter: returns HTML untouched.
+    class Null < Base
+      extend T::Sig
+
+      sig { override.params(html: String).returns(String) }
+      def inline(html)
+        html
+      end
+
+      sig { override.returns(T::Boolean) }
+      def noop?
+        true
+      end
+    end
+  end
+end

data/lib/active_mail/inliner/premailer.rb

@@ -0,0 +1,22 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ActiveMail
+  module Inliner
+    class Premailer < Base
+      extend T::Sig
+
+      sig { override.params(html: String).returns(String) }
+      def inline(html)
+        # premailer is a hard runtime dependency (the default inliner), so require
+        # can't fail — unlike the optional Roadie adapter, which guards LoadError.
+        require 'premailer'
+        # warn_level NONE: premailer's un-inlinable-CSS warnings are noise at delivery
+        # time; the quality layer is where coverage gaps should surface.
+        ::Premailer.new(html, with_html_string: true, warn_level: ::Premailer::Warnings::NONE).to_inline_css
+      end
+    end
+  end
+end

data/lib/active_mail/inliner/roadie.rb

@@ -0,0 +1,30 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ActiveMail
+  module Inliner
+    # Optional adapter — roadie is not a runtime dependency of the gem.
+    class Roadie < Base
+      extend T::Sig
+
+      sig { override.params(html: String).returns(String) }
+      def inline(html)
+        require_roadie!
+        ::Roadie::Document.new(html).transform
+      end
+
+      private
+
+      sig { void }
+      def require_roadie!
+        require 'roadie'
+      rescue LoadError
+        # Unify on Inliner::Error (LoadError is not a StandardError, so the
+        # interceptor's rescue would otherwise miss it); the LoadError is #cause.
+        raise ActiveMail::Inliner::Error, "ActiveMail::Inliner::Roadie requires the 'roadie' gem. Add it to your Gemfile."
+      end
+    end
+  end
+end

data/lib/active_mail/libxml.rb

@@ -0,0 +1,8 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ActiveMail
+  # libxml2 XML_HTML_UNKNOWN_TAG: emitted for every non-HTML4 tag (HTML5/custom
+  # tags), not actual malformedness. Shared by the engine and the quality layer.
+  LIBXML_UNKNOWN_TAG_CODE = 801
+end

data/lib/active_mail/parse_error_reporter.rb

@@ -0,0 +1,47 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+require_relative 'libxml'
+
+module ActiveMail
+  # Surfaces libxml2 recover-mode repairs that would otherwise silently change
+  # the rendered email, honoring ActiveMail.configuration.on_parse_error.
+  class ParseErrorReporter
+    extend T::Sig
+
+    sig { params(known_tags: T::Array[String]).void }
+    def initialize(known_tags)
+      # dup.freeze: the caller's array stays decoupled and cannot be mutated under us.
+      @known_tags = T.let(known_tags.dup.freeze, T::Array[String])
+    end
+
+    sig { params(errors: T::Array[Nokogiri::XML::SyntaxError]).void }
+    def call(errors)
+      mode = ::ActiveMail.configuration.on_parse_error
+      return if mode == :ignore
+
+      relevant = errors.reject { |error| known_tag_error?(error) }
+      return if relevant.empty?
+
+      messages = relevant.map { |error| error.message.to_s.strip }.join('; ')
+      raise ActiveMail::ParseError, messages if mode == :raise
+
+      ::ActiveMail.log_warning("[activemail] HTML parse issues: #{messages}")
+    end
+
+    private
+
+    sig { params(error: Nokogiri::XML::SyntaxError).returns(T::Boolean) }
+    def known_tag_error?(error)
+      return false unless error.code == LIBXML_UNKNOWN_TAG_CODE
+
+      # Fragile by necessity: the 801 error does not carry the tag name, only
+      # the libxml2 message text does. Locked by test against the pinned
+      # Nokogiri; revisit on bump if that test breaks.
+      tag = error.message.to_s[/Tag (\S+) invalid/, 1]
+      !tag.nil? && @known_tags.include?(tag)
+    end
+  end
+end

data/lib/active_mail/quality/configuration.rb

@@ -0,0 +1,56 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+require_relative 'guard'
+
+module ActiveMail
+  module Quality
+    class Configuration
+      extend T::Sig
+
+      sig { returns(Guard) }
+      attr_reader :guard
+
+      sig { params(value: T.untyped).void }
+      def guard=(value)
+        raise TypeError, "guard must be an ActiveMail::Quality::Guard, got #{value.class}" unless value.is_a?(Guard)
+
+        @guard = value
+      end
+
+      sig { returns(String) }
+      attr_reader :output_dir
+
+      sig { params(value: String).void }
+      def output_dir=(value)
+        raise ArgumentError, 'output_dir must not be blank' if value.strip.empty?
+
+        @output_dir = value
+      end
+
+      # Preview keys ("preview_name#email") that MUST render and pass the guard;
+      # a failure on any of these aborts the rake task. Other previews are only
+      # reported.
+      sig { returns(T::Array[String]) }
+      def required_previews
+        @required_previews.dup.freeze
+      end
+
+      sig { params(value: T.untyped).returns(T::Array[String]) }
+      def required_previews=(value)
+        raise TypeError, "#{value.inspect} (#{value.class}) does not respond to 'to_a'" unless value.respond_to?(:to_a)
+
+        @required_previews = value.to_a.map(&:to_s)
+      end
+
+      sig { void }
+      def initialize
+        @guard = T.let(Guard.new, Guard)
+        @output_dir = T.let('tmp/active_mail_previews', String)
+        @required_previews = T.let([], T::Array[String])
+      end
+    end
+  end
+end