activemail 1.2.3 → 2.0.0

data/app/assets/stylesheets/activemail/_grid.scss

@@ -1,3 +1,5 @@
+@use "settings" as *;
+
 // Gutters are unconditional padding (inlined by the CSS inliner): the gem emits
 // none, and they must not depend on media queries (stripped by Gmail mobile).
 

data/app/assets/stylesheets/activemail/_settings.scss

@@ -1,5 +1,8 @@
-// All !default so a host app can pre-declare any value before importing the framework.
-@import "activemail/activemail_tokens";
+// Sass only lets `with (...)` configure !default variables of forwarded modules:
+// every configurable variable must live here or in the forwarded token bridge.
+@forward "activemail_tokens";
+@use "sass:color";
+@use "activemail_tokens" as *;
 
 // Typography
 $am-font-family: $am-font-body !default;
@@ -11,19 +14,19 @@ $am-background: $am-color-background !default;
 $am-muted: $am-color-muted !default;
 $am-border: $am-color-border !default;
 
-// Buttons
+// Buttons — a null border means no border at all.
 $am-button-primary-bg: $am-color-primary !default;
+$am-button-primary-color: $am-color-primary-text !default;
+$am-button-primary-border: $am-color-primary-border !default;
 $am-button-secondary-bg: $am-color-secondary !default;
-$am-button-color: $am-color-button-text !default;
-// Secondary falls back to filled-button defaults; override *-secondary-* for an outline variant.
-$am-button-secondary-color: $am-color-button-text !default;
-$am-button-secondary-border: transparent !default;
+$am-button-secondary-color: $am-color-secondary-text !default;
+$am-button-secondary-border: $am-color-secondary-border !default;
 $am-button-radius: $am-radius-button !default;
 
 // Info box
-$am-info-box-bg: $am-background !default;
-$am-info-box-border: $am-border !default;
-$am-info-box-text: $am-text !default;
+$am-info-box-background: $am-color-info-box-background !default;
+$am-info-box-border: $am-color-info-box-border !default;
+$am-info-box-text: $am-color-info-box-text !default;
 $am-box-radius: $am-radius-box !default;
 
 // Grid — the gem emits no gutters; we provide them via column padding. Width
@@ -31,3 +34,12 @@ $am-box-radius: $am-radius-box !default;
 // aligned with the transpiled markup (ghost tables, column max-width).
 $am-container-width: $am-grid-container-width !default;
 $am-gutter: $am-spacing-sm !default;
+$am-breakpoint: $am-container-width !default;
+
+// Dark mode
+$am-dark-bg: color.mix($am-color-text, $am-color-background, 96%) !default;
+$am-dark-surface: color.mix($am-color-text, $am-color-background, 92%) !default;
+$am-dark-panel: color.mix($am-color-text, $am-color-background, 82%) !default;
+$am-dark-text: color.mix($am-color-background, $am-color-text, 88%) !default;
+$am-dark-muted: $am-color-muted !default;
+$am-dark-link: $am-button-primary-bg !default;

data/app/assets/stylesheets/activemail/_utilities.scss

@@ -1,3 +1,5 @@
+@use "settings" as *;
+
 // Alignment and visibility utilities.
 
 .text-center {
@@ -32,7 +34,7 @@
   overflow: hidden;
 }
 
-@media only screen and (min-width: 596px) {
+@media only screen and (min-width: $am-breakpoint) {
   .show-for-large {
     display: block !important;
     font-size: inherit;

data/app/assets/stylesheets/activemail/activemail.scss

@@ -1,11 +1,12 @@
 // ActiveMail email framework entry point. Critical styles are inlined by the
 // configured CSS inliner (Gmail mobile strips <style>); only media-query and
 // dark-mode enhancements stay in the <head>.
-@import "activemail/settings";
-@import "activemail/grid";
-@import "activemail/components";
-@import "activemail/utilities";
-@import "activemail/dark";
+@forward "settings";
+@use "settings" as *;
+@use "grid";
+@use "components";
+@use "utilities";
+@use "dark";
 
 body,
 table,

data/app/helpers/active_mail/styles_helper.rb

@@ -1,29 +1,28 @@
 # typed: false
 # frozen_string_literal: true
 
+require 'activemail/asset_pipeline'
+
 module ActiveMail
-  # Embeds the compiled framework CSS as a <style> block so the Premailer adapter
-  # (string-only) inlines it — it can't fetch the stylesheet_link_tag's asset URL.
+  # Embeds the compiled CSS as a <style> block: the inliners take an HTML string
+  # and cannot fetch the digest URL a stylesheet_link_tag would emit.
   module StylesHelper
-    FRAMEWORK_STYLESHEET = 'activemail/activemail.css'
-
-    # '' (not raise) when the asset can't be read — degrades to the link fallback,
-    # but warns, since the email then ships unstyled.
-    def activemail_inline_styles
-      css = activemail_compiled_css
-      if css.blank?
-        ActiveMail.log_warning('[activemail] framework stylesheet could not be read from the asset pipeline; ' \
-                               'email ships without inlined framework CSS')
-        return ''.html_safe
-      end
+    FRAMEWORK_STYLESHEET = 'activemail/activemail'
 
+    def activemail_inline_styles(*logical_paths)
+      paths = logical_paths.empty? ? [FRAMEWORK_STYLESHEET] : logical_paths
+      css = paths.map { |path| activemail_compiled_css(path.to_s) }.join("\n")
       content_tag(:style, css.html_safe, type: 'text/css')
     end
 
     private
 
-    def activemail_compiled_css
-      ActiveMail::CompiledStylesheet.read(FRAMEWORK_STYLESHEET)
+    def activemail_compiled_css(logical_path)
+      asset = logical_path.end_with?('.css') ? logical_path : "#{logical_path}.css"
+      css = ActiveMail::AssetPipeline.current.read(asset)
+      return css if css.present?
+
+      raise ActiveMail::StylesheetNotFound, "stylesheet #{asset.inspect} is missing or empty in the asset pipeline"
     end
   end
 end

data/app/views/layouts/activemail/mailer.html.inky-erb

@@ -15,12 +15,7 @@
       </xml>
     </noscript>
     <![endif]-->
-    <%# Embedded so the Premailer adapter (HTML-string only) can inline the framework CSS. %>
     <%= activemail_inline_styles %>
-    <%# Fallback for when activemail_inline_styles cannot read the compiled asset %>
-    <%# (CDN-only host, compile=false without precompile); redundant otherwise, as the %>
-    <%# embed's rules are idempotent once inlined. %>
-    <%= stylesheet_link_tag "activemail/activemail", media: "all" %>
   </head>
 
   <body style="margin:0;padding:0;word-spacing:normal;">

data/lib/activemail/asset_pipeline/base.rb

@@ -0,0 +1,47 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module ActiveMail
+  module AssetPipeline
+    class Base
+      extend T::Sig
+      extend T::Helpers
+
+      abstract!
+
+      sig { params(app: T.untyped).void }
+      def initialize(app)
+        @app = T.let(app, T.untyped)
+        @cache = T.let({}, T::Hash[String, String])
+      end
+
+      sig { params(logical_path: String).returns(T.nilable(String)) }
+      def read(logical_path)
+        return fetch(logical_path) unless cache?
+
+        cached = @cache[logical_path]
+        return cached if cached
+
+        fetch(logical_path).tap { |css| @cache[logical_path] = css if css }
+      end
+
+      sig { params(_paths: T::Array[String]).void }
+      def register_precompile(_paths); end
+
+      private
+
+      sig { abstract.params(logical_path: String).returns(T.nilable(String)) }
+      def fetch(logical_path); end
+
+      sig { returns(T.untyped) }
+      attr_reader :app
+
+      sig { returns(T::Boolean) }
+      def cache?
+        !app.config.enable_reloading
+      end
+    end
+  end
+end

data/lib/activemail/asset_pipeline/null.rb

@@ -0,0 +1,19 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ActiveMail
+  module AssetPipeline
+    class Null < Base
+      extend T::Sig
+
+      private
+
+      sig { override.params(_logical_path: String).returns(T.nilable(String)) }
+      def fetch(_logical_path)
+        nil
+      end
+    end
+  end
+end

data/lib/activemail/asset_pipeline/propshaft.rb

@@ -0,0 +1,19 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ActiveMail
+  module AssetPipeline
+    class Propshaft < Base
+      extend T::Sig
+
+      private
+
+      sig { override.params(logical_path: String).returns(T.nilable(String)) }
+      def fetch(logical_path)
+        app.assets.load_path.find(logical_path)&.content&.force_encoding(Encoding::UTF_8)
+      end
+    end
+  end
+end

data/lib/activemail/asset_pipeline/sprockets.rb

@@ -0,0 +1,39 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ActiveMail
+  module AssetPipeline
+    class Sprockets < Base
+      extend T::Sig
+
+      sig { override.params(paths: T::Array[String]).void }
+      def register_precompile(paths)
+        app.config.assets.precompile += paths
+      end
+
+      private
+
+      # app.assets is the live environment (compile = true); with precompiled
+      # assets it is nil and only the manifest can resolve the logical path.
+      sig { override.params(logical_path: String).returns(T.nilable(String)) }
+      def fetch(logical_path)
+        environment = app.assets
+        return environment.find_asset(logical_path)&.to_s if environment
+
+        manifest_source(logical_path)
+      end
+
+      sig { params(logical_path: String).returns(T.nilable(String)) }
+      def manifest_source(logical_path)
+        manifest = app.assets_manifest
+        compiled = manifest&.assets&.[](logical_path)
+        return unless compiled
+
+        path = File.join(manifest.directory, compiled)
+        File.read(path) if File.file?(path)
+      end
+    end
+  end
+end

data/lib/activemail/asset_pipeline.rb

@@ -0,0 +1,35 @@
+# typed: false
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+require_relative 'asset_pipeline/base'
+require_relative 'asset_pipeline/sprockets'
+require_relative 'asset_pipeline/propshaft'
+require_relative 'asset_pipeline/null'
+
+module ActiveMail
+  module AssetPipeline
+    class << self
+      extend T::Sig
+
+      # Never respond_to?: Sprockets' config.assets is an OrderedOptions that
+      # answers it for any key.
+      sig { params(app: T.untyped).returns(ActiveMail::AssetPipeline::Base) }
+      def for(app)
+        if defined?(::Sprockets::Railtie)
+          Sprockets.new(app)
+        elsif defined?(::Propshaft)
+          Propshaft.new(app)
+        else
+          Null.new(app)
+        end
+      end
+
+      sig { returns(ActiveMail::AssetPipeline::Base) }
+      def current
+        @current ||= T.let(self.for(::Rails.application), T.nilable(ActiveMail::AssetPipeline::Base))
+      end
+    end
+  end
+end

data/lib/activemail/components/base.rb

@@ -21,22 +21,20 @@ module ActiveMail
       end
     end
 
-    # Public extension point: subclass, implement #transform(node, inner), then register.
+    # `inner` is an opaque slot: interpolate it exactly once; the engine moves the
+    # already transformed children there.
     class Base
       extend T::Sig
       extend T::Helpers
 
       abstract!
 
-      IGNORED_ON_PASSTHROUGH = T.let(
-        %w[class id href size large no-expander small target rel up size-sm size-lg style].freeze,
-        T::Array[String]
-      )
+      HANDLED_ATTRIBUTES = T.let(%w[class style].freeze, T::Array[String])
+      LINK_ATTRIBUTES = T.let(%w[href target rel].freeze, T::Array[String])
 
       # Layout tables: presentation role (a11y) and zeroed legacy spacing.
       TABLE_RESET = 'role="presentation" border="0" cellpadding="0" cellspacing="0"'
-
-      BUTTON_PADDING = 'padding:12px 24px;'
+      TABLE_RESET_ATTRIBUTES = T.let(%w[role border cellpadding cellspacing].freeze, T::Array[String])
 
       sig { params(core: ::ActiveMail::Core).void }
       def initialize(core)
@@ -57,19 +55,33 @@ module ActiveMail
         CGI.escapeHTML(value.to_s)
       end
 
-      # Author attributes are untrusted: "abc".to_i would silently become 0.
       sig { params(value: T.untyped).returns(T.nilable(Integer)) }
       def positive_int(value)
-        # The RBI types Integer(exception: false) as non-nilable; it does return nil.
-        int = T.let(Integer(value.to_s, exception: false), T.nilable(Integer))
-        int if int&.positive?
+        ActiveMail.parse_positive_integer(value)
       end
 
-      sig { params(node: Nokogiri::XML::Node).returns(String) }
-      def pass_through_attributes(node)
-        node.attributes.reject { |name, _| IGNORED_ON_PASSTHROUGH.include?(name.downcase) }.map do |name, value|
-          %(#{name}="#{escape_attr(value)}" )
-        end.join
+      sig { overridable.returns(T::Array[String]) }
+      def consumed_attributes
+        []
+      end
+
+      sig do
+        params(node: Nokogiri::XML::Node, classes: T.nilable(String), layout_style: String, skip: T::Array[String]).returns(String)
+      end
+      def root_attributes(node, classes:, layout_style: '', skip: [])
+        "#{class_attribute(node, classes)}#{passthrough_attributes(node, skip)}#{style_attribute(node, layout_style)}"
+      end
+
+      sig { params(node: Nokogiri::XML::Node, classes: T.nilable(String)).returns(String) }
+      def class_attribute(node, classes)
+        merged = combine_classes(node, classes)
+        merged.empty? ? '' : %( class="#{escape_attr(merged)}")
+      end
+
+      sig { params(node: Nokogiri::XML::Node, skip: T::Array[String]).returns(String) }
+      def passthrough_attributes(node, skip = [])
+        reserved = HANDLED_ATTRIBUTES + consumed_attributes + skip
+        node.attributes.except(*reserved).map { |name, attr| %( #{name}="#{escape_attr(attr.value)}") }.join
       end
 
       # Author style merged after layout (a duplicated style attribute would be
@@ -84,7 +96,7 @@ module ActiveMail
 
       sig { params(node: Nokogiri::XML::Node, klass: String).returns(T::Boolean) }
       def class?(node, klass)
-        !((node.attr('class') || '') =~ /(^|\s)#{Regexp.escape(klass)}($|\s)/).nil?
+        node['class'].to_s.split.include?(klass)
       end
 
       sig { params(node: Nokogiri::XML::Node, extra_classes: T.nilable(String)).returns(String) }
@@ -94,14 +106,6 @@ module ActiveMail
         (existing + to_add).uniq.join(' ')
       end
 
-      sig { params(node: Nokogiri::XML::Node, extra_classes: T.nilable(String)).returns(String) }
-      def combine_attributes(node, extra_classes = nil)
-        classes = combine_classes(node, extra_classes)
-        # Escape like the other attribute paths: a literal " in the class would
-        # otherwise reopen the attribute.
-        [pass_through_attributes(node), %(class="#{escape_attr(classes)}")].join
-      end
-
       sig { params(node: Nokogiri::XML::Node).returns(String) }
       def link_attributes(node)
         target = node.attributes['target']&.value
@@ -112,24 +116,16 @@ module ActiveMail
         ].join
       end
 
+      sig { params(node: Nokogiri::XML::Node, inner: String, before: String, after: String).returns(String) }
+      def anchor(node, inner, before: '', after: '')
+        %(<a#{before} href="#{escape_attr(node.attr('href'))}"#{link_attributes(node)}#{after}>#{inner}</a>)
+      end
+
       sig { params(node: Nokogiri::XML::Node, target: T.nilable(String)).returns(T.nilable(String)) }
       def resolve_rel(node, target)
         rel = node.attributes['rel']&.value
         rel = nil if rel&.strip&.empty?
-        rel || (ActiveMail.configuration.blank_link_rel if target == '_blank')
-      end
-
-      # Outlook-safe nested-table structure kept in one place for <button> and <cta>.
-      sig do
-        params(outer_classes: String, inner: String, cell_style: String, outer_extra: String).returns(String)
-      end
-      def bulletproof_button_table(outer_classes:, inner:, cell_style: '', outer_extra: '')
-        cell = cell_style.empty? ? '<td>' : %(<td style="#{cell_style}">)
-        [
-          %(<table class="#{outer_classes}" #{TABLE_RESET}><tbody><tr><td>),
-          %(<table #{TABLE_RESET}><tbody><tr>#{cell}#{inner}</td></tr></tbody></table>),
-          %(</td>#{outer_extra}</tr></tbody></table>)
-        ].join
+        rel || (core.config.blank_link_rel if target == '_blank')
       end
 
       sig { returns(Integer) }

data/lib/activemail/components/block_grid.rb

@@ -1,18 +1,25 @@
 # typed: strict
 # frozen_string_literal: true
 
-require_relative 'base'
+require_relative 'table_component'
 
 module ActiveMail
   module Components
-    class BlockGrid < Base
+    class BlockGrid < TableComponent
       extend T::Sig
 
       sig { override.params(node: Nokogiri::XML::Node, inner: String).returns(String) }
       def transform(node, inner)
         up = positive_int(node.attr('up'))
-        classes = combine_classes(node, ['block-grid', up && "up-#{up}"].compact.join(' '))
-        %(<table class="#{classes}" #{TABLE_RESET}#{style_attribute(node, 'width:100%;')}><tbody><tr>#{inner}</tr></tbody></table>)
+        classes = ['block-grid', up && "up-#{up}"].compact.join(' ')
+        %(<table#{root_attributes(node, classes: classes, layout_style: 'width:100%;')} #{TABLE_RESET}><tbody><tr>#{inner}</tr></tbody></table>)
+      end
+
+      private
+
+      sig { override.returns(T::Array[String]) }
+      def consumed_attributes
+        [*super, 'up']
       end
     end
   end

data/lib/activemail/components/button.rb

@@ -1,39 +1,16 @@
 # typed: strict
 # frozen_string_literal: true
 
-require_relative 'base'
+require_relative 'button_renderer'
 
 module ActiveMail
   module Components
-    class Button < Base
+    class Button < ButtonRenderer
       extend T::Sig
 
-      sig { override.params(node: Nokogiri::XML::Node, inner: String).returns(String) }
-      def transform(node, inner)
-        expand = class?(node, 'expand')
-        inner = anchor(node, inner, expand) if node.attr('href')
-        inner = "<center>#{inner}</center>" if expand
-
-        expander = expand ? '<td class="expander"></td>' : ''
-        # CSS-driven by design: colors come from .button rules, not inline tokens —
-        # a distinct robustness model from <cta>, which inlines its palette.
-        bulletproof_button_table(
-          outer_classes: combine_classes(node, 'button'),
-          inner: inner,
-          outer_extra: expander
-        )
-      end
-
-      private
-
-      sig { params(node: Nokogiri::XML::Node, inner: String, expand: T::Boolean).returns(String) }
-      def anchor(node, inner, expand)
-        links = link_attributes(node)
-        extra = expand ? ' align="center" class="float-center"' : ''
-        # Padding on the <a> makes the whole button a clickable target.
-        link_style = "display:inline-block;text-decoration:none;#{BUTTON_PADDING}"
-        attrs = %(#{pass_through_attributes(node)}href="#{escape_attr(node.attr('href'))}"#{links}#{extra})
-        %(<a #{attrs}#{style_attribute(node, link_style)}>#{inner}</a>)
+      sig { override.returns(String) }
+      def root_class
+        'button'
       end
     end
   end

data/lib/activemail/components/button_renderer.rb

@@ -0,0 +1,65 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ActiveMail
+  module Components
+    # Bulletproof button shared by <button> and <cta>: styles are inlined from the
+    # tokens (read at transform time) so it survives clients that strip <style>.
+    class ButtonRenderer < Base
+      extend T::Sig
+      extend T::Helpers
+
+      abstract!
+
+      CONTROL_PADDING = 'padding:12px 24px;'
+
+      sig { abstract.returns(String) }
+      def root_class; end
+
+      sig { override.params(node: Nokogiri::XML::Node, inner: String).returns(String) }
+      def transform(node, inner)
+        style = core.config.tokens.button_style(class?(node, 'secondary') ? :secondary : :primary)
+        expand = class?(node, 'expand')
+        width = expand ? ' style="width:100%;"' : ''
+        [
+          %(<table#{class_attribute(node, root_class)} #{TABLE_RESET}#{width}><tbody><tr><td>),
+          %(<table #{TABLE_RESET}#{width}><tbody><tr><td style="#{cell_style(style, expand)}">),
+          control(node, inner, style, expand),
+          '</td></tr></tbody></table></td></tr></tbody></table>'
+        ].join
+      end
+
+      private
+
+      sig { override.returns(T::Array[String]) }
+      def consumed_attributes
+        LINK_ATTRIBUTES
+      end
+
+      # Padding on the control makes the whole button a clickable target.
+      sig { params(node: Nokogiri::XML::Node, inner: String, style: ActiveMail::Tokens::ButtonStyle, expand: T::Boolean).returns(String) }
+      def control(node, inner, style, expand)
+        css = control_style(style, expand)
+        extra = passthrough_attributes(node)
+        return %(<span#{extra}#{style_attribute(node, css)}>#{inner}</span>) unless node.attr('href')
+
+        anchor(node, inner, before: extra, after: style_attribute(node, css))
+      end
+
+      # The outline lives on the cell only: repeating it on the control would double the line.
+      sig { params(style: ActiveMail::Tokens::ButtonStyle, expand: T::Boolean).returns(String) }
+      def cell_style(style, expand)
+        border = style.border ? "border:1px solid #{style.border};" : ''
+        "background:#{style.background};border-radius:#{style.radius};#{border}#{'text-align:center;' if expand}"
+      end
+
+      sig { params(style: ActiveMail::Tokens::ButtonStyle, expand: T::Boolean).returns(String) }
+      def control_style(style, expand)
+        "display:#{expand ? 'block' : 'inline-block'};text-decoration:none;#{CONTROL_PADDING}" \
+          "background:#{style.background};color:#{style.color};font-weight:bold;border-radius:#{style.radius};"
+      end
+    end
+  end
+end

data/lib/activemail/components/callout.rb

@@ -1,20 +1,19 @@
 # typed: strict
 # frozen_string_literal: true
 
-require_relative 'base'
+require_relative 'table_component'
 
 module ActiveMail
   module Components
-    class Callout < Base
+    class Callout < TableComponent
       extend T::Sig
 
       sig { override.params(node: Nokogiri::XML::Node, inner: String).returns(String) }
       def transform(node, inner)
         classes = combine_classes(node, 'callout-inner')
-        attributes = pass_through_attributes(node)
         [
-          %(<table #{attributes}class="callout" #{TABLE_RESET}#{style_attribute(node, 'width:100%;')}><tbody><tr>),
-          %(<th class="#{classes}">#{inner}</th><th class="expander"></th>),
+          %(<table class="callout"#{passthrough_attributes(node)}#{style_attribute(node, 'width:100%;')} #{TABLE_RESET}><tbody><tr>),
+          %(<th class="#{escape_attr(classes)}">#{inner}</th><th class="expander"></th>),
           '</tr></tbody></table>'
         ].join
       end

data/lib/activemail/components/center.rb

@@ -8,16 +8,14 @@ module ActiveMail
     class Center < Base
       extend T::Sig
 
-      sig { override.params(node: Nokogiri::XML::Node, _inner: String).returns(String) }
-      def transform(node, _inner)
-        elements = node.elements
-        elements.each do |child|
+      sig { override.params(node: Nokogiri::XML::Node, inner: String).returns(String) }
+      def transform(node, inner)
+        node.elements.each do |child|
           child['align'] = 'center'
           child['class'] = combine_classes(child, 'float-center')
         end
-        items = elements.css('.menu-item').to_a.concat(elements.css('item').to_a)
-        items.each { |item| item['class'] = combine_classes(item, 'float-center') }
-        node.to_s
+        node.css('.menu-item').each { |item| item['class'] = combine_classes(item, 'float-center') }
+        %(<center#{root_attributes(node, classes: nil)}>#{inner}</center>)
       end
     end
   end