herb 0.10.4-aarch64-linux-gnu → 0.11.0-aarch64-linux-gnu

data/lib/herb/engine/component_tags/constant_resolver.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "resolver"
+
+module Herb
+  class Engine
+    module ComponentTags
+      # Resolves a tag name that is a Ruby constant, so `<Card />` becomes `render Card.new` and
+      # `<Users::Card />` becomes `render Users::Card.new`.
+      #
+      class ConstantResolver < Resolver
+        TAG_NAME = /\A[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*\z/
+
+        #: (String) -> bool
+        def handles?(tag_name)
+          tag_name.match?(TAG_NAME)
+        end
+
+        #: (String, Hash[String, String], block: bool) -> String
+        def render_code(tag_name, attributes, block: false) # rubocop:disable Lint/UnusedMethodArgument
+          return "render #{tag_name}.new" if attributes.empty?
+
+          "render #{tag_name}.new(#{keyword_arguments(attributes)})"
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/component_tags/partial_resolver.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "resolver"
+
+module Herb
+  class Engine
+    module ComponentTags
+      # Resolves a dot separated tag name to a partial path, so `<Users.ProfileCard />` becomes
+      # `render "users/profile_card"`.
+      #
+      # The tag name has to parse first, which needs the `dot_notation_tags` parser option.
+      #
+      class PartialResolver < Resolver
+        TAG_NAME = /\A[A-Z][A-Za-z0-9_]*(?:\.[A-Z][A-Za-z0-9_]*)+\z/
+
+        #: (String) -> bool
+        def handles?(tag_name)
+          tag_name.match?(TAG_NAME)
+        end
+
+        #: (String, Hash[String, String], block: bool) -> String
+        def render_code(tag_name, attributes, block: false)
+          path = partial_path(tag_name)
+
+          if block
+            return %(render layout: "#{path}") if attributes.empty?
+
+            %(render layout: "#{path}", locals: { #{keyword_arguments(attributes)} })
+          else
+            return %(render "#{path}") if attributes.empty?
+
+            %(render "#{path}", #{keyword_arguments(attributes)})
+          end
+        end
+
+        private
+
+        # `Users.ProfileCard` -> `users/profile_card`
+        #: (String) -> String
+        def partial_path(tag_name)
+          tag_name.split(".").map { |segment| underscore(segment) }.join("/")
+        end
+
+        #: (String) -> String
+        def underscore(segment)
+          segment
+            .gsub(/([A-Z])(?=[A-Z][a-z])/, '\1_')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .downcase
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/component_tags/resolver.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Herb
+  class Engine
+    module ComponentTags
+      # Decides what a tag renders to. A resolver claims a tag name through `handles?` and turns
+      # it into the Ruby source for a `render` call through `render_code`.
+      #
+      # Resolution is static: a resolver only ever sees the tag name and its attributes, never the
+      # application it compiles against.
+      #
+      class Resolver
+        #: (String) -> bool
+        def handles?(tag_name)
+          raise NotImplementedError, "#{self.class} must implement #handles?"
+        end
+
+        #: (String, Hash[String, String], block: bool) -> String
+        def render_code(tag_name, attributes, block:)
+          raise NotImplementedError, "#{self.class} must implement #render_code"
+        end
+
+        private
+
+        #: (Hash[String, String]) -> String
+        def keyword_arguments(attributes)
+          attributes.map { |name, value| "#{name}: #{value}" }.join(", ")
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/component_tags/visitor.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require_relative "../../../herb"
+require_relative "../../visitor/experimental"
+require_relative "constant_resolver"
+require_relative "partial_resolver"
+
+module Herb
+  class Engine
+    module ComponentTags
+      class Visitor < Herb::Visitor
+        extend Herb::Visitor::Experimental
+
+        TAG_NAME_SEPARATOR = /::|\./
+        KEYWORD_NAME = /\A[a-z_][A-Za-z0-9_]*\z/
+
+        ARRAY_PROPERTIES = [:children, :body, :statements].freeze
+        NODE_PROPERTIES = [:subsequent, :else_clause, :end_node, :rescue_clause, :ensure_clause].freeze
+
+        required_parser_option track_locations: true
+        experimental "`ComponentTags::Visitor` is experimental. Its output and API may change."
+
+        #: (?resolvers: Array[Herb::Engine::ComponentTags::Resolver]) -> void
+        def initialize(resolvers: [ConstantResolver.new, PartialResolver.new])
+          super()
+
+          @resolvers = resolvers
+        end
+
+        def visit_document_node(node)
+          super
+          replace_component_nodes_recursive(node)
+        end
+
+        #: () -> String
+        def inspect
+          "#<#{self.class.name}>"
+        end
+
+        private
+
+        def replace_component_nodes_recursive(node)
+          ARRAY_PROPERTIES.each do |property|
+            next unless node.respond_to?(property) && node.send(property).is_a?(Array)
+
+            array = node.send(property)
+
+            array.each_with_index do |child, index|
+              if component?(child)
+                array[index] = transform_to_erb_component(child)
+              else
+                replace_component_nodes_recursive(child)
+              end
+            end
+          end
+
+          NODE_PROPERTIES.each do |property|
+            next unless node.respond_to?(property) && node.send(property)
+
+            replace_component_nodes_recursive(node.send(property))
+          end
+        end
+
+        #: (Herb::AST::Node?) -> bool
+        def component?(node)
+          return false unless node.is_a?(Herb::AST::HTMLElementNode)
+
+          tag_name = node.tag_name&.value
+
+          return false unless tag_name
+          return false unless resolver_for(tag_name)
+
+          tag_name.split(TAG_NAME_SEPARATOR).all? { |segment| segment.match?(/[a-z]/) }
+        end
+
+        def transform_to_erb_component(element_node)
+          tag_name = element_node.tag_name&.value
+          attributes = extract_attributes_from_element(element_node)
+          body = element_node.body || []
+
+          body.each do |child|
+            replace_component_nodes_recursive(child)
+          end
+
+          body.each_with_index do |child, index|
+            body[index] = transform_to_erb_component(child) if component?(child)
+          end
+
+          if body.empty?
+            erb_content_node(element_node, "#{render_code(tag_name, attributes, block: false)} ")
+          else
+            erb_block_node(element_node, "#{render_code(tag_name, attributes, block: true)} do ", body)
+          end
+        end
+
+        #: (String) -> Herb::Engine::ComponentTags::Resolver?
+        def resolver_for(tag_name)
+          @resolvers.find { |resolver| resolver.handles?(tag_name) }
+        end
+
+        #: (String?, Hash[String, String], block: bool) -> String?
+        def render_code(tag_name, attributes, block:)
+          return nil unless tag_name
+
+          resolver_for(tag_name)&.render_code(tag_name, attributes, block: block)
+        end
+
+        #: (Herb::AST::HTMLElementNode) -> Hash[String, String]
+        def extract_attributes_from_element(element_node)
+          open_tag = element_node.open_tag
+          attributes = {} #: Hash[String, String]
+
+          return attributes unless open_tag.is_a?(Herb::AST::HTMLOpenTagNode)
+
+          children = open_tag.children
+
+          return attributes unless children
+
+          children.each do |child|
+            next unless child.is_a?(Herb::AST::HTMLAttributeNode)
+
+            original_name = attribute_name(child)
+
+            next unless original_name
+
+            directive = original_name.start_with?(":")
+            name = original_name.delete_prefix(":").tr("-", "_")
+
+            next unless name.match?(KEYWORD_NAME)
+            next if attributes.key?(name)
+
+            attributes[name] = attribute_value(child, directive: directive)
+          end
+
+          attributes
+        end
+
+        #: (Herb::AST::HTMLAttributeNode) -> String?
+        def attribute_name(node)
+          children = node.name&.children
+
+          return nil unless children
+
+          name = children.filter_map { |child| child.content if child.is_a?(Herb::AST::LiteralNode) }.join
+
+          name.empty? ? nil : name
+        end
+
+        #: (Herb::AST::HTMLAttributeNode, directive: bool) -> String
+        def attribute_value(node, directive:)
+          value = node.value
+
+          return "true" unless value
+
+          children = value.children || []
+
+          return directive ? "nil" : '""' if children.empty?
+          return ruby_code_from(children) if directive
+
+          string_literal_from(children)
+        end
+
+        #: (Array[Herb::AST::Node]) -> String
+        def ruby_code_from(children)
+          children.filter_map { |child|
+            case child
+            when Herb::AST::LiteralNode then child.content
+            when Herb::AST::ERBContentNode then child.content&.value&.strip
+            end
+          }.join.strip
+        end
+
+        #: (Array[Herb::AST::Node]) -> String
+        def string_literal_from(children)
+          parts = children.filter_map { |child|
+            case child
+            when Herb::AST::LiteralNode
+              escape(child.content.to_s)
+            when Herb::AST::ERBContentNode
+              code = child.content&.value&.strip
+
+              "\#{#{code}}" if code
+            end
+          }
+
+          %("#{parts.join}")
+        end
+
+        #: (String) -> String
+        def escape(content)
+          dumped = content.dump
+
+          dumped[1...-1].to_s
+        end
+
+        #: (Herb::AST::HTMLElementNode, String) -> Herb::AST::ERBContentNode
+        def erb_content_node(element_node, code)
+          Herb::AST::ERBContentNode.build(
+            location: element_node.location,
+            tag_opening: Herb::Token.from("TOKEN_ERB_START", "<%="),
+            content: Herb::Token.from("TOKEN_ERB_CONTENT", " #{code}"),
+            tag_closing: Herb::Token.from("TOKEN_ERB_END", "%>"),
+            valid: true
+          )
+        end
+
+        #: (Herb::AST::HTMLElementNode, String, Array[Herb::AST::Node]) -> Herb::AST::ERBBlockNode
+        def erb_block_node(element_node, code, body)
+          Herb::AST::ERBBlockNode.build(
+            location: element_node.location,
+            tag_opening: Herb::Token.from("TOKEN_ERB_START", "<%="),
+            content: Herb::Token.from("TOKEN_ERB_CONTENT", " #{code}"),
+            tag_closing: Herb::Token.from("TOKEN_ERB_END", "%>"),
+            body: body,
+            end_node: erb_end_node(element_node)
+          )
+        end
+
+        #: (Herb::AST::HTMLElementNode) -> Herb::AST::ERBEndNode
+        def erb_end_node(element_node)
+          Herb::AST::ERBEndNode.build(
+            location: element_node.location,
+            tag_opening: Herb::Token.from("TOKEN_ERB_START", "<%"),
+            content: Herb::Token.from("TOKEN_ERB_CONTENT", " end "),
+            tag_closing: Herb::Token.from("TOKEN_ERB_END", "%>")
+          )
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/css_inliner/inliner.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Herb
+  class Engine
+    module CSSInliner
+      # Writes the CSS a template rendered into `style` attributes on the markup it applies to.
+      #
+      #     Herb::Engine::CSSInliner.inliner = Herb::Engine::CSSInliner::Inliner.new
+      #
+      # A template compiled with `CSSInliner::Visitor` hands everything it rendered to
+      # `CSSInliner.inline`, and this is what answers. Where the CSS came from is not something this
+      # has to know: a `<style>` block the template wrote, a block `ScopedStyle::Visitor` narrowed,
+      # and a stylesheet read at compile time all arrive the same way, and all of it is matched
+      # against the markup in the same buffer.
+      #
+      # Without an inliner installed, or if one fails, the markup is answered as it was rendered. The
+      # `<style>` blocks are still in it, so the CSS applies as it was written and the template is
+      # correct either way. Installing this is what turns a block into attributes, not what makes it
+      # work.
+      #
+      # The markup is wrapped in a `<template>` before it is parsed. A template renders a fragment,
+      # and a fragment is parsed in whatever context it is given: parsed as a body, a file whose
+      # roots are `<tr>` or `<td>` is not mangled but dropped, and `<tr><td>x</td></tr>` comes back
+      # as `x`. `<template>` is the one context that holds every element a file can start with.
+      #
+      # `keep` says whether the blocks the CSS came from are written out again, which they have to be
+      # when the CSS holds anything a `style` attribute cannot say. An inliner drops those rules
+      # instead of keeping them, so CSS holding `:hover` or `@media` is kept and says the rest twice.
+      # Which it is, is decided when the template is compiled.
+      #
+      # Anything answering `inline_fragment` with the markup and a stylesheet can stand in for
+      # `CSSInline::CSSInliner`, which is the only thing this needs it to be.
+      #
+      class Inliner
+        OPEN = "<template>" #: String
+        CLOSE = "</template>" #: String
+
+        #: (?keeping: untyped, ?dropping: untyped) -> void
+        def initialize(keeping: nil, dropping: nil)
+          @keeping = keeping || build(true)
+          @dropping = dropping || build(false)
+        end
+
+        #: (String, ?String, ?keep: bool) -> String
+        def call(html, css = "", keep: false)
+          inliner = keep ? @keeping : @dropping
+          inlined = inliner.inline_fragment("#{OPEN}#{html}#{CLOSE}", css)
+
+          inlined.delete_prefix(OPEN).delete_suffix(CLOSE)
+        rescue StandardError
+          html
+        end
+
+        #: () -> String
+        def inspect
+          "#<#{self.class.name}>"
+        end
+
+        private
+
+        #: (bool) -> untyped
+        def build(keep)
+          require "css_inline"
+
+          ::CSSInline::CSSInliner.new(keep_style_tags: keep, inline_style_tags: true) # steep:ignore
+        end
+      end
+
+      @inliner = nil #: untyped
+
+      class << self
+        attr_writer :inliner #: untyped
+
+        #: () -> untyped
+        def inliner
+          return @inliner unless @inliner.nil?
+
+          @inliner = build
+        end
+
+        #: (String, ?String, ?keep: bool) -> String
+        def inline(html, css = "", keep: false)
+          built = inliner
+
+          return html unless built
+
+          built.call(html, css, keep: keep)
+        end
+
+        private
+
+        #: () -> untyped
+        def build
+          Inliner.new
+        rescue LoadError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/css_inliner/visitor.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require_relative "../../visitor/context_aware"
+require_relative "../../visitor/diagnostics"
+require_relative "../../visitor/experimental"
+require_relative "inliner"
+
+module Herb
+  class Engine
+    module CSSInliner
+      # Writes the CSS a template rendered into `style` attributes on the markup it applies to.
+      #
+      #     Herb::Engine.new(source, filename: path, visitors: [
+      #       Herb::Engine::CSSInliner::Visitor.new(stylesheets: ["app/assets/email.css"])
+      #     ])
+      #
+      # A `style` attribute is the only way to say something an email client reads, and this is how a
+      # stylesheet gets there. The CSS is matched against the markup once the file has rendered, not
+      # when it is compiled, because that is the first moment the markup exists.
+      #
+      # Every `<style>` block the template rendered is inlined, whoever wrote it. A block the author
+      # wrote by hand, and a block `ScopedStyle::Visitor` narrowed, are both read out of the markup
+      # by the inliner itself. `stylesheets` are files read when the template is compiled and carried
+      # in the compiled template, so nothing reads a file to render one and the CSS a template was
+      # compiled against cannot change under it.
+      #
+      # Because it inlines every block it finds, this belongs in a stack that wants all of its CSS on
+      # the elements. That is what an email wants. A page that meant a `<style>` block to stay a
+      # `<style>` block does not.
+      #
+      # What a template holds when this runs is what it decides about, so it has to run after anything
+      # that rewrites the blocks, which the stack checks. A `ScopedStyle::Visitor` delivering anywhere
+      # other than `:inline` takes its block out of the markup, and reading a template before that
+      # happens is reading a block that will not be there to inline.
+      #
+      class Visitor < Herb::Visitor
+        extend Herb::Visitor::Experimental
+        include Herb::Visitor::ContextAware
+        include Herb::Visitor::Diagnostics
+
+        AT_RULES = /@(?:media|supports|keyframes|font-face|container|layer)\b/ #: Regexp
+        STATEFUL = /::?(?:hover|focus|active|visited|target|before|after|placeholder|marker|selection)\b/ #: Regexp
+
+        experimental "Inlining CSS is experimental. Which declarations reach a `style` attribute and which are left in the block may change."
+
+        #: () -> bool
+        def self.reads_style_blocks?
+          true
+        end
+
+        #: (?stylesheets: Array[String]) -> void
+        def initialize(stylesheets: [])
+          super()
+
+          @stylesheets = stylesheets #: Array[String]
+          @css = nil #: String?
+          @blocks = [] #: Array[String?]
+        end
+
+        #: (Herb::AST::DocumentNode) -> void
+        def visit_document_node(node)
+          @blocks = [] #: Array[String?]
+
+          super
+        end
+
+        #: (Herb::AST::HTMLElementNode) -> void
+        def visit_html_element_node(node)
+          @blocks << block_css(node) if node.tag_name&.value&.downcase == "style"
+
+          super
+        end
+
+        #: (Herb::AST::DocumentNode) -> void
+        def finish(node)
+          @css = read_stylesheets
+
+          report_missing_inliner
+
+          return if @css.nil? || @css.empty?
+
+          children = node.children
+
+          return unless children.is_a?(Array)
+
+          @blocks << @css
+
+          children.unshift(literal_node("<style>#{@css}</style>"))
+
+          nil
+        end
+
+        #: (String) -> String
+        def postamble(carried)
+          return carried if @blocks.empty?
+
+          "::Herb::Engine::CSSInliner.inline((#{carried.strip}), keep: #{keeping?})\n"
+        end
+
+        #: () -> String
+        def inspect
+          return "#<#{self.class.name}>" if @stylesheets.empty?
+
+          "#<#{self.class.name} stylesheets=#{@stylesheets.join(", ")}>"
+        end
+
+        private
+
+        #: () -> void
+        def report_missing_inliner
+          return unless CSSInliner.inliner == false
+
+          warning(
+            "#{self.class.name} writes CSS onto the markup with the `css_inline` gem, which is not installed, so the markup is left with the blocks it was written with. Add `css_inline` to write it onto the elements.",
+            nil,
+            code: "css-inliner-without-an-inliner"
+          )
+
+          nil
+        end
+
+        #: (Herb::AST::HTMLElementNode) -> String?
+        def block_css(node)
+          children = node.body || []
+
+          return nil unless children.all?(Herb::AST::LiteralNode)
+
+          children.filter_map { |child| child.content if child.is_a?(Herb::AST::LiteralNode) }.join
+        end
+
+        #: () -> bool
+        def keeping?
+          return true if @blocks.any?(&:nil?)
+
+          @blocks.compact.any? { |css| css.match?(AT_RULES) || css.match?(STATEFUL) }
+        end
+
+        #: (String) -> Herb::AST::LiteralNode
+        def literal_node(content)
+          Herb::AST::LiteralNode.build(content: content.dup)
+        end
+
+        #: () -> String?
+        def read_stylesheets
+          return "" if @stylesheets.empty?
+
+          @stylesheets.filter_map { |stylesheet| read_stylesheet(stylesheet) }.join("\n")
+        end
+
+        #: (String) -> String
+        def resolve(stylesheet)
+          return stylesheet if Pathname.new(stylesheet).absolute? || context.project_path.nil?
+
+          File.join(context.project_path.to_s, stylesheet)
+        end
+
+        #: (String) -> String?
+        def read_stylesheet(stylesheet)
+          path = resolve(stylesheet)
+
+          File.read(path)
+        rescue SystemCallError, IOError => e
+          warning(
+            "A stylesheet `#{self.class.name}` was told to inline could not be read, so the markup it applies to was left without it. It failed with `#{e.message}`.",
+            nil,
+            code: "css-inliner-stylesheet-that-could-not-be-read"
+          )
+
+          nil
+        end
+      end
+    end
+  end
+end