premailer 1.32.0 → 1.33.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2186c26ccc50f22227a6dbbf53b4cd3b5ae5f8bebdbdc190b0e7fd0e5a152565
-  data.tar.gz: 84becf9c1329983be14a427eef560806fb23ceb05847b7c5484033fe2fda0248
+  metadata.gz: b30285e2878d409bc44b84777bc055096cd023b666dd7453164586fb8e97a7dd
+  data.tar.gz: 47bfb72f292747619e4067332275f40f85bd225725977507a57e97bebffbdd71
 SHA512:
-  metadata.gz: c489d4a76330f66eeb60793faebc2839591870ee261179c0d9369ef95e5194d967f2b0f1aec31f16edb9355e363766fcb9245e67f13d2bb39b53cf1598ab8e36
-  data.tar.gz: 48a0cf85f5d2c2e3cbc2e7a5b21e70bf0e9e9215b2067703b9f9e5574342be25901aa639b1fcbdc3889e1d883905ad30e1e300d188fee68fd043f0de1588e2f2
+  metadata.gz: 77556f76f97fa85e0047b1e45ebdd530853d3cc33794366b3979b4475920a6b87163853d8349b2f507e6fbafa24a2a747529f448f3335b3b03446713266b3ab2
+  data.tar.gz: 50ac02894d5fef9ccc6e5b8df0e75feac8dcedff61eacdca4fac43230f9802319907648377666f132e19da46585965020adf128d70d0a7e7d12348d70103f7d9

data/README.md

@@ -39,6 +39,9 @@ premailer.warnings.each do |w|
 end
 ```
 
+The plain-text version excludes the contents of `<style>` and `<script>`
+elements, including styles retained in HTML with `preserve_styles: true`.
+
 ## Adapters
 
 1. nokogiri (default)
@@ -53,6 +56,10 @@ Picking an adapter:
 Premailer::Adapter.use = :nokogiri_fast
 ```
 
+When converting image CSS to HTML attributes, only `float: left` and
+`float: right` become `align` attributes. Other values, such as `float: none`,
+remain in the inline style because they have no equivalent HTML alignment.
+
 ## Ruby Compatibility
 
 See .github/workflows/actions.yml for which ruby versions are tested. JRuby support is close, contributors are welcome.
@@ -72,6 +79,9 @@ Premailer looks for a few CSS attributes that make working with tables a bit eas
 
 Each of these CSS declarations will be copied to appropriate element's attribute.
 
+Background image URLs on tables are copied to the HTML `background` attribute.
+Gradients remain in inline CSS because that attribute only supports image URLs.
+
 For example
 
 ```css
@@ -127,6 +137,10 @@ Premailer.new(
 
 [available options](https://premailer.github.io/premailer/Premailer.html#initialize-instance_method)
 
+For the current options, see the [constructor source](https://github.com/premailer/premailer/blob/master/lib/premailer/premailer.rb).
+
+Verbose diagnostics are written to stderr. The command-line tool keeps its generated HTML on stdout, including when `--verbose` is enabled.
+
 ### Loading CSS from local/private hosts
 
 css_parser 3+ blocks fetching remote CSS (`<link>`, `@import`) from hosts that resolve to loopback/private IPs
@@ -137,6 +151,11 @@ To allow them, when the html is trusted:
 Premailer.new(html, with_html_string: true, allow_local_network: true)
 ```
 
+### Subresource Integrity
+
+Remote `<link rel="stylesheet">` tags with an `integrity` attribute are verified before inlining.
+A stylesheet whose hash does not match is dropped (or raises `CssParser::IntegrityError` with `io_exceptions: true`).
+
 ## Support for CSS variables
 
 The gem does not automatically replace CSS variables with their static values.
@@ -219,6 +238,29 @@ A few areas that are particularly in need of love:
 * Improved test coverage
 * Move un-repeated background images defined in CSS for Outlook
 
+## Generating API documentation
+
+Generate the API reference with [YARD](https://yardoc.org/) from the repository root:
+
+```sh
+bundle install
+bundle exec yard doc
+```
+
+Open the generated files in a browser. On macOS:
+
+```sh
+open doc/index.html # all docs
+open doc/Premailer.html # constructor and its options
+```
+
+The generated `doc/` and `.yardoc/` directories are ignored by Git.
+
+To update the [hosted documentation](https://premailer.github.io/premailer/), a maintainer
+regenerates the reference for the desired version and copies the contents of `doc/` to
+the root of the [`gh-pages` branch](https://github.com/premailer/premailer/tree/gh-pages).
+After reviewing, committing, and pushing those changes, GitHub Pages publishes that branch's root.
+
 ## Credits and code
 
 Thanks to [all the wonderful contributors](https://github.com/premailer/premailer/contributors) for their updates.

data/lib/premailer/adapter/nokogiri.rb

@@ -6,6 +6,11 @@ class Premailer
     # Nokogiri adapter
     module Nokogiri
       WIDTH_AND_HIGHT = ['width', 'height'].freeze
+      # Selectors made only of element names, classes, ids, combinators and
+      # pseudo-classes without arguments: no attribute, string, function or escape
+      # can hide a "." that is not a class.
+      PLAIN_SELECTOR = /\A[\w\s.#>+~*:-]+\z/
+      CLASS_IN_SELECTOR = /\.([\w-]+)/
 
       include AdapterHelper::RgbToHex
       # Merge CSS into the HTML document.
@@ -31,6 +36,10 @@ class Premailer
           rs = rule_set_cache.fetch(style) { rule_set_cache[style] = build_rule_set(style, 1000) }
           rules_by_node[el] = rs ? [rs] : []
         end
+        # A selector requiring a class that no element carries cannot match:
+        # skip its (costly) document-wide search.
+        classes_in_doc = doc.xpath('.//@class').flat_map { |attribute| attribute.value.split }.to_set
+
         # Iterate through the rules and merge them into the HTML
         @css_parser.each_selector(:all) do |selector, declaration, specificity, media_types|
           # Save un-mergable rules separately
@@ -49,6 +58,8 @@ class Premailer
                 @unmergable_rules.add_rule_set!(CssParser::RuleSet.new(selectors: selector, block: declaration))
               end
 
+              next if selector_requires_absent_class?(selector, classes_in_doc)
+
               # Change single ID CSS selectors into xpath so that we can match more
               # than one element.  Added to work around dodgy generated code.
               selector.gsub!(/\A\#([\w_\-]+)\Z/, '*[@id=\1]')
@@ -176,6 +187,9 @@ class Premailer
         # Duplicate CSS attributes as HTML attributes
         if related_el_name
           Premailer::RELATED_ATTRIBUTES[related_el_name].each do |css_attr, html_attr|
+            next if css_gradient?(css_attr, merged)
+            next if css_float_without_alignment?(css_attr, merged)
+
             unless merged[css_attr].empty?
               new_val = merged[css_attr].dup
 
@@ -209,6 +223,11 @@ class Premailer
         [merged.declarations_to_s, attributes]
       end
 
+      def selector_requires_absent_class?(selector, classes_in_doc) # :nodoc:
+        PLAIN_SELECTOR.match?(selector) &&
+          selector.scan(CLASS_IN_SELECTOR).any? { |(name)| !classes_in_doc.include?(name) }
+      end
+
       # Build an expanded rule set for folding. Returns nil (and optionally
       # swallows the error, mirroring the old fold-time rescue) on bad CSS.
       def build_rule_set(block, specificity) # :nodoc:
@@ -302,7 +321,9 @@ class Premailer
         end
         encoding = @options[:input_encoding] || (RUBY_PLATFORM == 'java' ? nil : 'BINARY')
         doc = if @options[:html_fragment]
-          ::Nokogiri::HTML.fragment(thing, encoding)
+          # libxml2 cannot serialize a fragment parsed as binary (sparklemotion/nokogiri#553):
+          # without an encoding, Nokogiri uses the string's own, or UTF-8 if it is binary.
+          ::Nokogiri::HTML.fragment(thing, (encoding unless encoding.to_s.match?(/\A(ASCII-8BIT|BINARY)\z/i)))
         else
           ::Nokogiri::HTML(thing, nil, encoding, &:recover)
         end

data/lib/premailer/adapter/nokogiri_fast.rb

@@ -85,6 +85,9 @@ class Premailer
           # Duplicate CSS attributes as HTML attributes
           if Premailer::RELATED_ATTRIBUTES.key?(el.name) && @options[:css_to_attributes]
             Premailer::RELATED_ATTRIBUTES[el.name].each do |css_attr, html_attr|
+              next if css_gradient?(css_attr, merged)
+              next if css_float_without_alignment?(css_attr, merged)
+
               if el[html_attr].nil? && !merged[css_attr].empty?
                 new_val = merged[css_attr].dup
 
@@ -245,7 +248,9 @@ class Premailer
         end
         encoding = @options[:input_encoding] || (RUBY_PLATFORM == 'java' ? nil : 'BINARY')
         doc = if @options[:html_fragment]
-          ::Nokogiri::HTML.fragment(thing, encoding)
+          # libxml2 cannot serialize a fragment parsed as binary (sparklemotion/nokogiri#553):
+          # without an encoding, Nokogiri uses the string's own, or UTF-8 if it is binary.
+          ::Nokogiri::HTML.fragment(thing, (encoding unless encoding.to_s.match?(/\A(ASCII-8BIT|BINARY)\z/i)))
         else
           ::Nokogiri::HTML(thing, nil, encoding, &:recover)
         end

data/lib/premailer/adapter/nokogumbo.rb

@@ -80,6 +80,9 @@ class Premailer
           # Duplicate CSS attributes as HTML attributes
           if Premailer::RELATED_ATTRIBUTES.key?(el.name) && @options[:css_to_attributes]
             Premailer::RELATED_ATTRIBUTES[el.name].each do |css_attr, html_attr|
+              next if css_gradient?(css_attr, merged)
+              next if css_float_without_alignment?(css_attr, merged)
+
               if el[html_attr].nil? && !merged[css_attr].empty?
                 new_val = merged[css_attr].dup
 

data/lib/premailer/html_to_plain_text.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-require 'htmlentities'
+require 'nokogiri'
 
 # Support functions for Premailer
 module HtmlToPlainText
@@ -20,6 +20,9 @@ module HtmlToPlainText
     # text version
     txt.gsub!(/<!-- start text\/html -->.*?<!-- end text\/html -->/m, '')
 
+    # Metadata is not readable text, even when styles are preserved in HTML.
+    txt.gsub!(/<(script|style)\b[^>]*>.*?<\/\1\s*>/im, '')
+
     # replace images with their alt attributes
     # for img tags with "" for attribute quotes
     # with or without closing tag
@@ -35,9 +38,6 @@ module HtmlToPlainText
     # <img alt=''>
     txt.gsub!(/<img[^>]+?alt='([^']*)'[^>]*>/i, '\1')
 
-    # remove script tags and content
-    txt.gsub!(/<script.*?\/script>/m, '')
-
     # links
     txt.gsub!(/<a\s+([^>]+)>(.*?)<\/a>/im) do |s|
       text = $2.strip
@@ -101,9 +101,8 @@ module HtmlToPlainText
     # strip remaining tags
     txt.gsub!(/<\/?[^>]*>/, '')
 
-    # decode HTML entities
-    he = HTMLEntities.new
-    txt = he.decode(txt)
+    # decode HTML entities; a textarea context parses as RCDATA, so a stray "<" stays text
+    txt = Nokogiri::HTML5::DocumentFragment.new(Nokogiri::HTML5::Document.new, txt, "textarea").text
 
     # word wrap
     txt = word_wrap(txt, line_length)

data/lib/premailer/premailer.rb

@@ -271,6 +271,29 @@ class Premailer
 
   protected
 
+  # Keep e.g. background-image: image-set(linear-gradient(red, blue), url(a.png))
+  # in CSS: a URL-only HTML background attribute cannot represent its gradient.
+  def css_gradient?(css_attr, merged) # :nodoc:
+    return false unless css_attr == 'background-image'
+
+    # Ignore gradient-like text inside URLs and quoted strings.
+    value = merged[css_attr].gsub(CssParser::URI_RX, '').gsub(CssParser::RE_STRING, '')
+    value.match?(
+      /(?:\A|[,(])\s*                 # Start of a value, list item, or nested function
+        (?:-[a-z]+-)?                 # Optional vendor prefix, e.g. -webkit-
+        (?:repeating-)?               # Optional repeating gradient
+        (?:linear|radial|conic)-gradient\( # Supported gradient function names
+      /ix
+    )
+  end
+
+  # Only left/right floats have an equivalent legacy image alignment.
+  def css_float_without_alignment?(css_attr, merged) # :nodoc:
+    return false unless css_attr == 'float'
+
+    !merged[css_attr].match?(/\A\s*(?:left|right)\s*(?:!important\s*)?;?\s*\z/i)
+  end
+
   def load_css_from_local_file!(path)
     css_block = +''
     path.delete_prefix!('file:')
@@ -332,7 +355,7 @@ class Premailer
             load_css_from_local_file!(link_uri)
           else
             warn "Loading css from uri: " + link_uri if @options[:verbose]
-            @css_parser.load_uri!(link_uri, { :only_media_types => [:screen, :handheld] })
+            @css_parser.load_uri!(link_uri, { :only_media_types => [:screen, :handheld], :integrity => tag.attributes['integrity']&.to_s })
           end
 
         elsif tag.to_s.strip =~ /^<style/i && @options[:include_style_tags]
@@ -414,7 +437,7 @@ class Premailer
         end
 
         if href.scheme && (href.scheme != 'http') && (href.scheme != 'https')
-          puts "Skipping append_query_string for: #{href} because scheme is no good" if @options[:verbose]
+          warn "Skipping append_query_string for: #{href} because scheme is no good" if @options[:verbose]
           next
         end
 

data/lib/premailer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 class Premailer
   # Premailer version.
-  VERSION = '1.32.0'
+  VERSION = '1.33.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: premailer
 version: !ruby/object:Gem::Version
-  version: 1.32.0
+  version: 1.33.0
 platform: ruby
 authors:
 - Alex Dunae
@@ -29,28 +29,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.19.0
+        version: 3.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.19.0
-- !ruby/object:Gem::Dependency
-  name: htmlentities
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 4.0.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 4.0.0
+        version: 3.1.0
 description: Improve the rendering of HTML emails by making CSS inline, converting
   links and warning about unsupported code.
 email: akzhan.abdulin@gmail.com