hanami-mailer 1.3.3 → 3.0.0

data/lib/hanami/mailer/view_integration.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module Hanami
+  class Mailer
+    # Integration module for Hanami::View support.
+    #
+    # This module is included when Hanami::View is available, providing automatic view building and
+    # settings inheritance.
+    #
+    # @api private
+    module ViewIntegration
+      def self.included(base)
+        base.class_eval do
+          # Prepend the initializer module to wrap initialization
+          prepend PrependedMethods
+
+          # Add class-level methods, including the lazily-built, memoized default view
+          extend ClassMethods
+
+          # Whether to automatically build views from exposures
+          # Set to false to disable automatic view integration behavior
+          setting :integrate_view, default: true
+
+          # The base class used when building the mailer's view. Defaults to Hanami::View, but
+          # may be set to an already-configured view class (such as a view class within a Hanami
+          # app), in which case the built view inherits that class's configuration — context,
+          # parts, scopes, paths, helpers and so on.
+          setting :view_class, default: Hanami::View
+
+          # Copy all settings from Hanami::View to support default view integration.
+          # This allows mailers to configure view-related settings (like layouts_dir,
+          # default_format, inflector, etc.) without having to manually redefine them.
+          existing_settings = config._settings.keys.to_set
+          Hanami::View.config._settings.each do |setting_def|
+            next if existing_settings.include?(setting_def.name)
+
+            setting(
+              setting_def.name,
+              default: setting_def.default,
+              constructor: setting_def.constructor,
+              **setting_def.options
+            )
+          end
+        end
+      end
+
+      # Class-level methods added to mailer classes when Hanami::View is available.
+      #
+      # @api private
+      module ClassMethods
+        # The auto-built default view for this mailer class.
+        #
+        # Built lazily on first access (the first render) and memoized, since it depends only on
+        # class-level state (config, exposures, class name) and is identical for every instance.
+        # Returns nil when view integration is disabled or no usable template paths are configured.
+        #
+        # Note: because the view is memoized on first render, later changes to view-related
+        # config or exposures are not reflected. Mailer classes are configured once at definition
+        # time, so this is intentional.
+        #
+        # @api private
+        def default_view
+          return @default_view if defined?(@default_view)
+
+          @default_view = config.integrate_view ? DefaultViewBuilder.call(self) : nil
+        end
+
+        # Defines an exposure that will be decorated with a matching view part.
+        #
+        # This is a shorthand for `expose(..., decorate: true)`.
+        #
+        # @see Mailer.expose
+        def decorate(*names, **options, &block)
+          expose(*names, **options, decorate: true, &block)
+        end
+      end
+
+      # Internal module for prepending view and render behavior.
+      # Wraps the base class to provide automatic view building and
+      # per-format template error handling.
+      #
+      # @api private
+      module PrependedMethods
+        # The view used for rendering: a per-instance override passed to the constructor, falling
+        # back to the mailer class's lazily-built, memoized default view.
+        def view
+          @view || self.class.default_view
+        end
+
+        # Renders HTML and text bodies, handling missing templates per format.
+        def render(input, format: nil)
+          html, html_error = try_render(:html, input) unless format == :text
+          text, text_error = try_render(:text, input) unless format == :html
+
+          # Tolerate one missing template if attempting to render both. Otherwise, consider any
+          # error as fatal.
+          raise html_error if html_error && (format || text_error)
+          raise text_error if text_error && format
+
+          [html, text]
+        end
+
+        def try_render(format, input)
+          [render_view(format, input), nil]
+        rescue Hanami::View::TemplateNotFoundError => exception
+          [nil, exception]
+        end
+      end
+
+      # Builder class for constructing default views.
+      # Keeps view building logic separate from mailer instances.
+      #
+      # @api private
+      class DefaultViewBuilder
+        class << self
+          # Builds a default view from exposures if Hanami::View is available.
+          def call(mailer_class)
+            view_class = mailer_class.config.view_class || Hanami::View
+
+            # A view needs paths to find its templates. These may be configured on the mailer, or
+            # inherited from an already-configured `view_class` (e.g. within a Hanami app).
+            paths = mailer_class.config.paths
+            if (paths.nil? || paths.empty?) && view_class.respond_to?(:config)
+              paths = view_class.config.paths
+            end
+            return nil if paths.nil? || paths.empty?
+
+            template = mailer_class.config.template
+            template ||= inferred_template(mailer_class)
+
+            build_view_class(
+              view_class: view_class,
+              template: template,
+              exposures: mailer_class.exposures,
+              config: mailer_class.config
+            )
+          end
+
+          private
+
+          # Infers template path from class name.
+          #
+          # @example
+          #   Mailers::WelcomeMailer -> "mailers/welcome_mailer"
+          def inferred_template(mailer_class)
+            return nil unless mailer_class.name
+
+            mailer_class.name
+              .gsub("::", "/")
+              .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+              .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+              .downcase
+          end
+
+          # rubocop:disable Metrics/AbcSize, Metrics/PerceivedComplexity
+
+          # Builds a Hanami::View instance from the mailer's configuration.
+          #
+          # The view is a subclass of the mailer's configured `view_class`, so it inherits that
+          # class's configuration. Only view settings the mailer has *explicitly* configured are
+          # applied as overrides, leaving an already-configured base class (such as a Hanami app's
+          # view) to provide its context, parts, scopes and helpers by inheritance. A standalone
+          # mailer (whose `view_class` is the unconfigured `Hanami::View`) still drives its own
+          # view via these overrides.
+          def build_view_class(view_class:, template:, exposures:, config:)
+            view_template = template
+            view_exposures = exposures
+            mailer_config = config
+
+            built = Class.new(view_class) do
+              Hanami::View.config._settings.each do |setting_def|
+                name = setting_def.name
+
+                # `template` and `layout` are handled explicitly below.
+                next if name == :template || name == :layout
+                next unless mailer_config.respond_to?(name)
+                next unless mailer_config.configured?(name)
+
+                self.config.public_send(:"#{name}=", mailer_config.public_send(name))
+              end
+
+              # Mailers do not use a layout by default, but one may be configured.
+              self.config.layout = mailer_config.configured?(:layout) ? mailer_config.layout : false
+
+              self.config.template = view_template if view_template
+
+              # Exposures are evaluated once, by the mailer, which passes their values to the view.
+              # The view only needs to pass each value through to the template (decorating it as
+              # required), so the procs are dropped here. Private exposures are internal to the
+              # mailer's evaluation and are not passed to the view at all.
+              view_exposures.each do |name, exposure|
+                next if exposure.private?
+
+                expose(name, **exposure.options)
+              end
+            end
+
+            built.new
+          end
+          # rubocop:enable Metrics/AbcSize, Metrics/PerceivedComplexity
+        end
+      end
+    end
+  end
+end