phlex-hanami 0.1.0 → 0.2.0.pre.alpha.2

data/lib/phlex/hanami/layout.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    # The base class for layouts.
+    #
+    # A layout is an ordinary Phlex class that yields the view's body. Name one `Views::Layout` in a
+    # slice's namespace and every view in that slice renders inside it; set a different one with
+    # `layout`, or opt out with `layout nil`.
+    #
+    # The view's body is rendered before the layout, so anything the view puts on the context — a
+    # `content_for(:page_title, ...)`, say — is already there when the layout renders its `head`.
+    #
+    # @example
+    #   # app/views/layout.rb
+    #   module MyApp
+    #     module Views
+    #       class Layout < Phlex::Hanami::Layout
+    #         def view_template
+    #           doctype
+    #           html do
+    #             head { title { hanami_context.content_for(:page_title) || "MyApp" } }
+    #             body { yield }
+    #           end
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    # @api public
+    # @since 0.2.0
+    class Layout < Phlex::HTML
+      include Renderable
+
+      # A layout is never itself wrapped in a layout.
+      layout nil
+    end
+  end
+end

data/lib/phlex/hanami/mailer/layout.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    module Mailer
+      # The base class for mail layouts.
+      #
+      # Name one `Views::Mailers::Layout` in a slice's namespace and every mail view in that slice
+      # renders inside it. The web layout is never used for mail; set a different one with `layout`,
+      # or opt out with `layout nil`.
+      #
+      # The layout is part of both message parts: the text part is converted from the HTML the
+      # layout produced, so a footer written once appears in both.
+      #
+      # @example
+      #   # app/views/mailers/layout.rb
+      #   module MyApp
+      #     module Views
+      #       module Mailers
+      #         class Layout < Phlex::Hanami::Mailer::Layout
+      #           def view_template
+      #             html do
+      #               body do
+      #                 yield
+      #                 p { "Sent by MyApp" }
+      #               end
+      #             end
+      #           end
+      #         end
+      #       end
+      #     end
+      #   end
+      #
+      # @api public
+      # @since 0.2.0
+      class Layout < Phlex::HTML
+        include Renderable
+
+        # A layout is never itself wrapped in a layout.
+        layout nil
+      end
+    end
+  end
+end

data/lib/phlex/hanami/mailer/renderable.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    module Mailer
+      # Makes a Phlex class renderable by a Hanami mailer.
+      #
+      # Include this into an existing `Phlex::SGML` subclass, or subclass {View}, which includes it
+      # already. It builds on {Phlex::Hanami::Renderable} and adds the three things mail needs: a
+      # context with no request behind it, a second format for the plain text part, and a layout
+      # convention of its own.
+      #
+      # @example
+      #   module MyApp
+      #     class MailerView < Phlex::HTML
+      #       include Phlex::Hanami::Mailer::Renderable
+      #     end
+      #   end
+      #
+      # @api public
+      # @since 0.2.0
+      module Renderable
+        # @api private
+        # @since 0.2.0
+        def self.included(view_class)
+          view_class.include(::Phlex::Hanami::Renderable)
+
+          # Order matters: a module included later sits higher in the lookup chain, so the mail
+          # methods have to go in after `Renderable`, not alongside them in this module.
+          view_class.include(MailMethods)
+          view_class.extend(ClassMethods)
+        end
+
+        # @api public
+        # @since 0.2.0
+        module ClassMethods
+          # Renders one part of a mail message.
+          #
+          # This is what `Hanami::Mailer#render_view` calls, once per part, with the format naming
+          # the part it wants. Hanami's mailer has no view context to hand over — there is no
+          # request to build one from — so a mail view builds the slice's own context itself.
+          #
+          # @param context [Object, nil] the Hanami view context, built from the slice when omitted
+          # @param format [Symbol] `:html` or `:text`
+          # @param input [Hash] the mailer's exposures
+          #
+          # @return [String] the rendered part
+          #
+          # @api public
+          # @since 0.2.0
+          def call(context: nil, format: :html, **input)
+            html = super(context: context || mail_context, **input)
+            return html unless format.to_s == "text"
+
+            new(**accepted_input(input)).text_body(html)
+          end
+
+          private
+
+          # A slice's conventional mail layout: `Views::Mailers::Layout`, if it defines one.
+          #
+          # The web layout is the wrong one for an email — it carries the stylesheets, scripts and
+          # page chrome no mail client wants — so mail looks for its own, and renders without a
+          # layout when the slice has none.
+          def default_layout
+            return nil unless slice
+            return nil unless slice.namespace.const_defined?(:Views, false)
+
+            views = slice.namespace.const_get(:Views, false)
+            return nil unless views.const_defined?(:Mailers, false)
+
+            mailers = views.const_get(:Mailers, false)
+            mailers.const_get(:Layout, false) if mailers.const_defined?(:Layout, false)
+          end
+
+          # The slice's view context, built without a request.
+          #
+          # The same class an action would be given, so a view reads the same in both places. What
+          # a request would have filled in — `request`, `session`, `flash`, `csrf_token` — is
+          # missing, and the context says so when a view reaches for it.
+          def mail_context
+            return nil unless slice
+
+            Extensions::Slice.view_context_class(slice).new
+          end
+        end
+
+        # What a mail view does differently.
+        #
+        # Included after `Phlex::Hanami::Renderable` so that it wins: a module included later sits
+        # higher in the lookup chain.
+        #
+        # @api private
+        # @since 0.2.0
+        module MailMethods
+          # Raises. An email is read outside the app, so a link in one needs a full URL.
+          #
+          # @raise [RelativePathError]
+          #
+          # @api public
+          # @since 0.2.0
+          def path(*, **)
+            raise RelativePathError, self.class
+          end
+
+          # The plain text part of the message.
+          #
+          # Called with the rendered HTML, layout and all, and converts it by default. Override it
+          # to write the text part by hand; the view's own state is there to read.
+          #
+          # @example
+          #   def text_body(_html)
+          #     "Welcome, #{@user.name}. Get started: #{url(:root)}"
+          #   end
+          #
+          # @param html [String] the rendered HTML part
+          #
+          # @return [String] the text part
+          #
+          # @api public
+          # @since 0.2.0
+          def text_body(html)
+            Text.call(html)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phlex/hanami/mailer/text.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    module Mailer
+      # Turns the HTML part of a message into its plain text alternative.
+      #
+      # This is regex over markup Phlex has just produced, not a general HTML parser. It knows the
+      # handful of things that matter in an email — anchors, lists, line breaks, block elements and
+      # the entities Phlex escapes — and leaves everything else on the floor. Markup from somewhere
+      # else, pasted into a view with `raw`, may not come out well.
+      #
+      # {Renderable#text_body} calls this. Override that method to write the text part by hand.
+      #
+      # @api public
+      # @since 0.2.0
+      class Text
+        # Elements that end a line of text, and so become a blank line.
+        #
+        # @api private
+        # @since 0.2.0
+        BLOCK_ELEMENTS = %w[
+          article blockquote div footer h1 h2 h3 h4 h5 h6 header hr li ol p section table td tr ul
+        ].freeze
+
+        # @api private
+        # @since 0.2.0
+        BLOCK_PATTERN = %r{</?(?:#{BLOCK_ELEMENTS.join('|')})\b[^>]*>}i
+
+        # The entities Phlex escapes, and the characters they stand for.
+        #
+        # @api private
+        # @since 0.2.0
+        ENTITIES = {
+          "&#39;" => "'",
+          "&amp;" => "&",
+          "&apos;" => "'",
+          "&gt;" => ">",
+          "&lt;" => "<",
+          "&nbsp;" => " ",
+          "&quot;" => '"',
+        }.freeze
+
+        # @api private
+        # @since 0.2.0
+        ENTITY_PATTERN = /&(?:amp|apos|gt|lt|nbsp|quot|#39);/
+
+        # Stand in for the angle brackets around a URL until the tags are gone, so that stripping
+        # tags does not eat the link the converter has just written.
+        #
+        # @api private
+        # @since 0.2.0
+        LINK_CLOSE = "\u0011"
+
+        # @api private
+        # @since 0.2.0
+        LINK_OPEN = "\u0010"
+
+        class << self
+          # Converts rendered HTML to plain text.
+          #
+          # @param html [String] the rendered HTML part
+          #
+          # @return [String] the text part
+          #
+          # @api public
+          # @since 0.2.0
+          def call(html)
+            text = body_of(html.to_s)
+            text = strip_hidden_elements(text)
+            text = expand_anchors(text)
+            text = expand_breaks(text)
+            text = expand_list_items(text)
+            text = expand_blocks(text)
+            text = strip_tags(text)
+            text = unescape(text)
+            restore_links(tidy(text))
+          end
+
+          private
+
+          # `Label <https://example.com/path>`, or one of the two when the other adds nothing.
+          def anchor_text(attributes, inner)
+            url = href_in(attributes)
+            label = strip_tags(inner).gsub(/\s+/, " ").strip
+            return label if url.empty?
+            return url if label.empty? || label == url
+
+            "#{label} #{LINK_OPEN}#{url}#{LINK_CLOSE}"
+          end
+
+          def body_of(html) = html[%r{<body\b[^>]*>(.*?)</body>}mi, 1] || html
+
+          def expand_anchors(html)
+            html.gsub(%r{<a\b([^>]*)>(.*?)</a>}mi) { anchor_text(Regexp.last_match(1), Regexp.last_match(2)) }
+          end
+
+          def expand_blocks(html) = html.gsub(BLOCK_PATTERN, "\n\n")
+
+          def expand_breaks(html) = html.gsub(%r{<br\b[^>]*/?>}i, "\n")
+
+          def expand_list_items(html) = html.gsub(%r{</li\s*>}i, "").gsub(/<li\b[^>]*>/i, "\n- ")
+
+          def href_in(attributes)
+            match = attributes.match(/\bhref\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))/i)
+            return "" unless match
+
+            (match[1] || match[2] || match[3]).to_s.strip
+          end
+
+          def restore_links(text) = text.gsub(LINK_OPEN, "<").gsub(LINK_CLOSE, ">")
+
+          def strip_hidden_elements(html) = html.gsub(%r{<(head|style|script)\b[^>]*>.*?</\1\s*>}mi, "")
+
+          def strip_tags(html) = html.gsub(/<!--.*?-->/m, "").gsub(/<[^>]*>/, "")
+
+          def tidy(text) = text.gsub(/[ \t]+/, " ").gsub(/[ \t]+$/, "").gsub(/\n{3,}/, "\n\n").strip
+
+          def unescape(text) = text.gsub(ENTITY_PATTERN) { ENTITIES.fetch(Regexp.last_match(0)) }
+        end
+      end
+    end
+  end
+end

data/lib/phlex/hanami/mailer/view.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    module Mailer
+      # The base class for Phlex views rendered by a Hanami mailer.
+      #
+      # Subclass this for a mail view, or for an app-level base mail view. If you already have your
+      # own `Phlex::HTML` base class, include {Renderable} into it instead — the two are equivalent.
+      #
+      # A mailer finds its view by name, the way an action does: `MyApp::Mailers::Welcome` renders
+      # `MyApp::Views::Mailers::Welcome`.
+      #
+      # @example
+      #   # app/views/mailers/welcome.rb
+      #   module MyApp
+      #     module Views
+      #       module Mailers
+      #         class Welcome < Phlex::Hanami::Mailer::View
+      #           def initialize(user:) = @user = user
+      #
+      #           def view_template
+      #             h1 { "Welcome, #{@user.name}" }
+      #             p { a(href: url(:root)) { "Get started" } }
+      #           end
+      #         end
+      #       end
+      #     end
+      #   end
+      #
+      # @api public
+      # @since 0.2.0
+      class View < Phlex::HTML
+        include Renderable
+      end
+    end
+  end
+end

data/lib/phlex/hanami/mailer.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    # Phlex views for hanami-mailer.
+    #
+    # A mailer renders the same view twice, once for each part of the message, so a mail view
+    # answers to a format: {Mailer::View} renders markup for the HTML part and converts that markup
+    # for the text part. Everything else a view can do it can do too, except the parts of the
+    # context that only exist during a request.
+    #
+    # @example
+    #   # app/mailers/welcome.rb
+    #   module MyApp
+    #     module Mailers
+    #       class Welcome < Hanami::Mailer
+    #         from "hello@example.com"
+    #         to { |user| user.email }
+    #         subject "Welcome"
+    #
+    #         expose :user
+    #       end
+    #     end
+    #   end
+    #
+    #   # app/views/mailers/welcome.rb
+    #   module MyApp
+    #     module Views
+    #       module Mailers
+    #         class Welcome < Phlex::Hanami::Mailer::View
+    #           def initialize(user:) = @user = user
+    #
+    #           def view_template
+    #             h1 { "Welcome, #{@user.name}" }
+    #             p { a(href: url(:root)) { "Get started" } }
+    #           end
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    # @api public
+    # @since 0.2.0
+    module Mailer
+    end
+  end
+end