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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 066d1770e9e59fc2e7a2a1e5a333be685bdee0c94180efd155a578af2f47d224
-  data.tar.gz: dab7797c0500df8bdaeaf8c856628e9b6a876e88e95511fc5bdbe18f4a09c1a7
+  metadata.gz: eb2ded5cb201e8636daeba76f21fc25b297899eba517ce428d6fcc41450460f9
+  data.tar.gz: f8935646735d5d5e52faf6c48b5713dae2f4169c02e8162fc4356c32e5cf09bd
 SHA512:
-  metadata.gz: 3acf4d4ec8b5ada0374b05f249cfe838351b93b5ac06a41f5876543b9b8b0725b442e89f7fe7414a827bcc7290fa7a4849dab25ed75b0802e2c762d7913788c9
-  data.tar.gz: 72f5b9ba2a7bc3aa46c16d4d548eebacd5825efe6d7476cc29bb1167cb0b5547a5ffd18fcf5edb1eca732dff1ce777478696597ae86529d5190b7da64fb1dfa6
+  metadata.gz: 396360b1808f053b39c29047103c6f860c46ac6bf436890a483848c63639c1e382fc0ad34eefb61f58335a4d158783349670c2b0ee30a421473737c5111e2abf
+  data.tar.gz: 84fbc91b5c45c6ece40da01070cd64bd9b2702cbc19c10c1ba8eeb3d27cc7aab57e3e60434305b18021dc980cc0a1fff983a051d5cce33b09b200fd87667db52

data/CHANGELOG.md

@@ -1,5 +1,49 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
 ## [Unreleased]
 
-## [0.1.0] - 2024-12-07
+## [v0.2.0-alpha.2] - 2026-09-05
+
+### Added
+
+- Phlex views for [hanami-mailer]. A mailer renders the Phlex class whose container key matches its own, so
+  `MyApp::Mailers::Welcome` renders `MyApp::Views::Mailers::Welcome` with no configuration.
+- `Phlex::Hanami::Mailer::View` and `Phlex::Hanami::Mailer::Layout`, and `Phlex::Hanami::Mailer::Renderable` for an
+  existing `Phlex::HTML` base class.
+- A plain text alternative part, converted from the rendered HTML by `Phlex::Hanami::Mailer::Text`. Override
+  `text_body` on the view to write it by hand.
+- A mail layout convention: `Views::Mailers::Layout` in a slice wraps that slice's mail views.
+- Usage documentation under [docs/usage](docs/usage/README.md), covering views, layouts, the view context,
+  helpers, mailers and how the gem hooks into Hanami.
+- `Phlex::Hanami::MailerViewError`, raised when a mailer is paired with a Phlex view that is not a mail view,
+  rather than sending a message whose plain text part is markup.
+
+### Changed
+
+- `url` in a view returns a String. Hanami's routes helper returns a `URI`, which Phlex rejects as an attribute
+  value, so `a(href: url(:posts))` raised.
+
+### Fixed
+
+- `path` in a mail view raises `Phlex::Hanami::RelativePathError` instead of writing a relative link an email client
+  cannot follow.
+
+[hanami-mailer]: https://github.com/hanami/mailer
+
+## [v0.2.0-alpha.1] - 2026-09-04
+
+Initial alpha release by the new maintainer [@aaronmallen](https://github.com/aaronmallen).
+
+## [v0.1.0] - 2024-12-07
+
+Initial release, by the previous maintainer [@stephannv](https://github.com/stephannv).
 
-- Initial release
+[Unreleased]: https://github.com/aaronmallen/phlex-hanami/compare/0.2.0-alpha.2...HEAD
+[v0.2.0-alpha.2]: https://github.com/aaronmallen/phlex-hanami/compare/0.2.0-alpha.1...0.2.0-alpha.2
+[v0.2.0-alpha.1]: https://github.com/aaronmallen/phlex-hanami/releases/tag/0.2.0-alpha.1
+[v0.1.0]: https://github.com/stephannv/phlex-hanami/releases/tag/v0.1.0

data/{LICENSE.txt → LICENSE}

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (c) 2024 stephann
+Copyright (c) 2026 Aaron Allen
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,13 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/lib/phlex/hanami/context.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    # The view context used when the hanami-view gem is not bundled.
+    #
+    # Hanami builds a context once per request and hands it to the view as `context:`. When
+    # hanami-view is bundled that context is a `Hanami::View::Context` and this class is unused;
+    # otherwise phlex-hanami defines a `Views::Context` subclass of this in every slice.
+    #
+    # The public surface mirrors `Hanami::View::Context` so that a view reads the same either way.
+    #
+    # @api public
+    # @since 0.2.0
+    class Context
+      extend ::Hanami::SliceConfigurable
+
+      # @api private
+      # @since 0.2.0
+      def self.configure_for_slice(slice)
+        extend SliceConfiguredContext.new(slice)
+      end
+
+      # The app's inflector.
+      #
+      # @return [Dry::Inflector]
+      #
+      # @api public
+      # @since 0.2.0
+      attr_reader :inflector
+
+      # @see SliceConfiguredContext#define_new
+      #
+      # @api private
+      # @since 0.2.0
+      def initialize(inflector: nil, routes: nil, assets: nil, request: nil, i18n: nil, **)
+        @inflector = inflector
+        @routes = routes
+        @assets = assets
+        @request = request
+        @i18n = i18n
+        @content_for = {}
+      end
+
+      # The slice's assets.
+      #
+      # @return [Hanami::Assets]
+      #
+      # @raise [Hanami::ComponentLoadError] when hanami-assets is not bundled, or no assets exist
+      #
+      # @api public
+      # @since 0.2.0
+      def assets
+        raise ::Hanami::ComponentLoadError, "Assets not available. #{assets_hint}" unless @assets
+
+        @assets
+      end
+
+      # Store a string of markup for later use, or read back what was stored.
+      #
+      # @param key [Symbol] the content key
+      # @param value [String, nil] the content, when no block is given
+      #
+      # @return [String, nil]
+      #
+      # @api public
+      # @since 0.2.0
+      def content_for(key, value = nil)
+        if block_given?
+          @content_for[key] = yield
+          nil
+        elsif value
+          @content_for[key] = value
+          nil
+        else
+          @content_for[key]
+        end
+      end
+
+      # The current request's CSRF token.
+      #
+      # @return [String]
+      #
+      # @raise [Hanami::ComponentLoadError] when there is no request
+      #
+      # @api public
+      # @since 0.2.0
+      def csrf_token
+        request.session[::Hanami::Action::CSRFProtection::CSRF_TOKEN]
+      end
+
+      # The flash hash for the current request.
+      #
+      # @raise [Hanami::ComponentLoadError] when there is no request
+      #
+      # @api public
+      # @since 0.2.0
+      def flash
+        request.flash
+      end
+
+      # The slice's i18n backend.
+      #
+      # @raise [Hanami::ComponentLoadError] when the i18n gem is not bundled
+      #
+      # @api public
+      # @since 0.2.0
+      def i18n
+        raise ::Hanami::ComponentLoadError, "the i18n gem is required to access translations" unless @i18n
+
+        @i18n
+      end
+
+      # @api private
+      # @since 0.2.0
+      def initialize_copy(source)
+        super
+        @content_for = source.instance_variable_get(:@content_for).dup
+      end
+
+      # The current request, when the view is rendered from an action.
+      #
+      # @return [Hanami::Action::Request]
+      #
+      # @raise [Hanami::ComponentLoadError] when the view is not rendered from a request
+      #
+      # @api public
+      # @since 0.2.0
+      def request
+        unless @request
+          raise ::Hanami::ComponentLoadError, <<~MESSAGE
+            Request not available. Only views rendered from Hanami::Action instances have a request.
+          MESSAGE
+        end
+
+        @request
+      end
+
+      # Whether a request is available.
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      # @since 0.2.0
+      def request?
+        !!@request
+      end
+
+      # The app's routes helper.
+      #
+      # @return [Hanami::Slice::RoutesHelper]
+      #
+      # @raise [Hanami::ComponentLoadError] when hanami-router is not bundled or routes are undefined
+      #
+      # @api public
+      # @since 0.2.0
+      def routes
+        raise ::Hanami::ComponentLoadError, "the hanami-router gem is required to access routes" unless @routes
+
+        @routes
+      end
+
+      # The session for the current request.
+      #
+      # @raise [Hanami::ComponentLoadError] when there is no request
+      #
+      # @api public
+      # @since 0.2.0
+      def session
+        request.session
+      end
+
+      private
+
+      def assets_hint
+        if ::Hanami.bundled?("hanami-assets")
+          "Have you put files into your assets directory?"
+        else
+          "The hanami-assets gem is required to access assets."
+        end
+      end
+    end
+  end
+end

data/lib/phlex/hanami/errors/error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    # Base class for every error raised by phlex-hanami.
+    #
+    # @api public
+    # @since 0.2.0
+    class Error < StandardError
+    end
+  end
+end

data/lib/phlex/hanami/errors/mailer_view_error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    # Raised when a mailer's paired Phlex view cannot render a mail message.
+    #
+    # A mailer asks its view for two parts, and an ordinary view answers both with markup — which
+    # would ship an email whose plain text part is HTML. Better to say so than to send it.
+    #
+    # @api public
+    # @since 0.2.0
+    class MailerViewError < Error
+      # @api private
+      # @since 0.2.0
+      def initialize(mailer_class, view_class)
+        super(<<~MESSAGE)
+          #{mailer_class} is paired with #{view_class}, which is not a mail view.
+
+          A mail view renders both parts of the message. Subclass the mail base class:
+
+            class #{view_class} < Phlex::Hanami::Mailer::View
+
+          or include the module into the base class you already have:
+
+            include Phlex::Hanami::Mailer::Renderable
+        MESSAGE
+      end
+    end
+  end
+end

data/lib/phlex/hanami/errors/missing_context_error.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    # Raised when a view reaches for the Hanami view context but was rendered without one.
+    #
+    # @api public
+    # @since 0.2.0
+    class MissingContextError < Error
+      # @api private
+      # @since 0.2.0
+      def initialize(view_class)
+        super(<<~MESSAGE)
+          #{view_class} was rendered without a Hanami view context.
+
+          Views rendered from an action are given one automatically. When rendering a view yourself,
+          pass one:
+
+            #{view_class}.call(context: MyApp::Views::Context.new)
+        MESSAGE
+      end
+    end
+  end
+end

data/lib/phlex/hanami/errors/relative_path_error.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    # Raised when a mail view asks for a relative path.
+    #
+    # An email is read outside the app, so a relative path in one is a dead link. Mail views raise
+    # rather than render one.
+    #
+    # @api public
+    # @since 0.2.0
+    class RelativePathError < Error
+      # @api private
+      # @since 0.2.0
+      def initialize(view_class)
+        super(<<~MESSAGE)
+          #{view_class} asked for a relative path, and an email needs a full URL.
+
+          Use `url` instead:
+
+            a(href: url(:post, id: @post.id)) { @post.title }
+        MESSAGE
+      end
+    end
+  end
+end

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    module Extensions
+      # Pairs a Hanami mailer with a Phlex view.
+      #
+      # Prepended onto `Hanami::Mailer`, so it sits in front of hanami-mailer's own view handling
+      # and answers first. A mailer's view is any object taking `call(format:, **input)`, which a
+      # {Phlex::Hanami::Mailer::View} already is, so pairing is the whole of the integration:
+      # nothing here teaches hanami-mailer what Phlex is.
+      #
+      # @api private
+      # @since 0.2.0
+      module Mailer
+        # Prepends this onto `Hanami::Mailer`.
+        #
+        # Called from `phlex/hanami.rb` when hanami-mailer is bundled. Zeitwerk keeps the mail
+        # classes unloaded until something names one, but a prepend needs the constant, so the
+        # check belongs at the call site.
+        #
+        # @api private
+        # @since 0.2.0
+        def self.install
+          ::Hanami::Mailer.prepend(self)
+          ::Hanami::Mailer.singleton_class.prepend(ClassMethods)
+        end
+
+        # @api private
+        # @since 0.2.0
+        module ClassMethods
+          # @api private
+          # @since 0.2.0
+          def configure_for_slice(slice)
+            super
+            extend SliceConfigured.new(slice)
+          end
+
+          # The mailer's paired Phlex view, or nil when it has none.
+          #
+          # The key is derived the way hanami-mailer derives a template name: underscore the class
+          # name and drop the slice's own segment, so `MyApp::Mailers::Welcome` looks up
+          # `views.mailers.welcome`. Resolved through the container on every call rather than
+          # memoized, so code reloading is not defeated.
+          #
+          # @return [Class, nil]
+          #
+          # @raise [MailerViewError] when the paired view is a Phlex class that cannot render mail
+          #
+          # @api private
+          # @since 0.2.0
+          def phlex_view
+            mailer_slice = slice
+            return nil unless mailer_slice && name
+
+            key = "views.#{view_name(mailer_slice)}"
+            return nil unless mailer_slice.key?(key)
+
+            view = mailer_slice[key]
+            return nil unless view.is_a?(::Class) && view < ::Phlex::SGML
+            raise MailerViewError.new(self, view) unless view < ::Phlex::Hanami::Mailer::Renderable
+
+            view
+          end
+
+          # The slice this mailer belongs to, or nil when it is defined outside a slice namespace.
+          #
+          # @return [Hanami::Slice, nil]
+          #
+          # @api private
+          # @since 0.2.0
+          def slice
+            nil
+          end
+
+          private
+
+          def view_name(mailer_slice)
+            mailer_slice.inflector
+              .underscore(name)
+              .sub(%r{^#{mailer_slice.slice_name.path}/}, "")
+              .tr("/", ".")
+          end
+        end
+
+        # The view this mailer renders.
+        #
+        # A view passed to the constructor wins, then the paired Phlex view, then whatever
+        # hanami-mailer would have used on its own — so an app can render some of its mail with
+        # Phlex and the rest with templates.
+        #
+        # @return [Object, nil]
+        #
+        # @api private
+        # @since 0.2.0
+        def view
+          @view || self.class.phlex_view || super
+        end
+      end
+    end
+  end
+end

data/lib/phlex/hanami/extensions/slice.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    module Extensions
+      # Installs phlex-hanami into every slice, including the app.
+      #
+      # Prepended onto `Hanami::Slice::ClassMethods` so that it runs for the app and each of its
+      # slices as they are prepared. Two things happen:
+      #
+      # 1. Phlex classes are registered in the slice container as classes rather than instances.
+      #    `Dry::System` would otherwise call `new` on them while resolving, which raises for any
+      #    view with a real initializer, and a memoized Phlex instance can only render once.
+      # 2. A `Views::Context` is defined for the slice when hanami-view is not bundled, filling the
+      #    third-party slot `Hanami::Extensions::Action::SliceConfiguredAction#view_context_class`
+      #    looks in.
+      #
+      # @api private
+      # @since 0.2.0
+      module Slice
+        # Returns Phlex classes as classes, and everything else as the loader would.
+        #
+        # `component.loader.constant` is what the default autoloading loader already calls, so no
+        # extra loading happens here and a constant that fails to load still raises
+        # `Dry::System::ComponentNotLoadableError`.
+        #
+        # @api private
+        # @since 0.2.0
+        COMPONENT_INSTANCE = proc { |component, *args, **kwargs|
+          constant = component.loader.constant(component)
+
+          if constant.is_a?(Class) && constant < Phlex::SGML
+            constant
+          else
+            component.loader.call(component, *args, **kwargs)
+          end
+        }
+
+        # @api private
+        # @since 0.2.0
+        def prepare(provider_name = nil)
+          result = super
+
+          unless provider_name
+            Slice.register_phlex_components(self)
+            Slice.define_view_context(self)
+          end
+
+          result
+        end
+
+        class << self
+          # Defines `Views::Context` for the slice when nothing else has.
+          #
+          # Does nothing when hanami-view is bundled, because Hanami defines its own richer context
+          # there, and returns the existing one when the user has defined it themselves.
+          #
+          # @return [Class, nil] the slice's context class
+          #
+          # @api private
+          # @since 0.2.0
+          def define_view_context(slice)
+            return if ::Hanami.bundled?("hanami-view")
+
+            namespace = views_namespace(slice)
+            return namespace.const_get(:Context, false) if namespace.const_defined?(:Context, false)
+
+            # The class is anonymous at this point, so the slice cannot be inferred from its name
+            # the way `Hanami::SliceConfigurable` would; configure it explicitly instead.
+            namespace.const_set(:Context, ::Class.new(Context).tap { |klass| klass.configure_for_slice(slice) })
+          end
+
+          # Installs {COMPONENT_INSTANCE} as the default for the slice container's component dirs.
+          #
+          # `Dry::System::Config::ComponentDirs` re-applies its defaults every time the dirs are
+          # read, and only where a dir has not configured the setting itself, so setting this after
+          # the dirs have been added covers all of them and clobbers nothing.
+          #
+          # @api private
+          # @since 0.2.0
+          def register_phlex_components(slice)
+            component_dirs = slice.container.config.component_dirs
+            return if component_dirs.configured?(:instance)
+
+            component_dirs.instance = COMPONENT_INSTANCE
+          end
+
+          # The class an action's view context is built from, for anything rendering outside a
+          # request that needs the same one.
+          #
+          # Reads the third-party slot `Hanami::Extensions::Action::SliceConfiguredAction` reads,
+          # so a mail view and a request view are given the same class.
+          #
+          # @return [Class]
+          #
+          # @api private
+          # @since 0.2.0
+          def view_context_class(slice)
+            return ::Hanami::Extensions::View::Context.context_class(slice) if ::Hanami.bundled?("hanami-view")
+
+            define_view_context(slice)
+          end
+
+          private
+
+          def views_namespace(slice)
+            if slice.namespace.const_defined?(:Views, false)
+              slice.namespace.const_get(:Views, false)
+            else
+              slice.namespace.const_set(:Views, ::Module.new)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phlex/hanami/helpers.rb

@@ -1,9 +1,68 @@
+# frozen_string_literal: true
+
+require "hanami/view"
+require "hanami/extensions/view/standard_helpers"
+
+# Hanami's helpers return `SafeString`s meant to be interpolated into a template. Marking the class
+# as a Phlex safe object lets Phlex emit them without escaping — both through `raw` and, more often,
+# as the return value of a block.
+Hanami::View::HTML::SafeString.include(Phlex::SGML::SafeObject)
+
 module Phlex
   module Hanami
+    # Hanami's standard helper library, for Phlex views that want it.
+    #
+    # Opt in per base class; it is not included in {View}, because it adds around twenty methods and
+    # needs the hanami-view gem, and neither should depend on what happens to be in your Gemfile.
+    #
+    # @example
+    #   module MyApp
+    #     class View < Phlex::Hanami::View
+    #       include Phlex::Hanami::Helpers
+    #     end
+    #   end
+    #
+    #   class Edit < MyApp::View
+    #     def view_template
+    #       raw form_for("post", path(:posts)) { |f| f.text_field(:title) + f.submit("Save") }
+    #     end
+    #   end
+    #
+    # Most of Hanami's helpers duplicate something Phlex already does better — Phlex escapes by
+    # default and is itself a tag builder — so reach for `form_for`, `format_number` and the asset
+    # helpers, and write everything else as ordinary Phlex.
+    #
+    # @api public
+    # @since 0.2.0
     module Helpers
-      def self.included(base)
-        base.include AssetsHelper
-        base.include ContextHelper
+      # Hanami's helper library defines two methods Phlex already owns.
+      #
+      # Both of Hanami's return strings to interpolate; Phlex's write into the output buffer.
+      # Letting Hanami's win breaks `raw` silently — the helper's output simply never appears — and
+      # `raw` is the method you need in order to emit a helper's result at all.
+      #
+      # @api private
+      # @since 0.2.0
+      OVERRIDDEN_METHODS = {
+        raw: Phlex::SGML.instance_method(:raw),
+        tag: Phlex::HTML.instance_method(:tag),
+      }.freeze
+
+      # Phlex's implementations, mixed back in over Hanami's.
+      #
+      # @api private
+      # @since 0.2.0
+      PhlexMethods = ::Module.new do
+        OVERRIDDEN_METHODS.each do |name, method|
+          define_method(name) { |*args, **options, &block| method.bind_call(self, *args, **options, &block) }
+        end
+      end
+
+      # @api private
+      # @since 0.2.0
+      def self.included(view_class)
+        view_class.include(::Hanami::Extensions::View::StandardHelpers)
+        view_class.include(PhlexMethods)
       end
     end
   end