phlex-hanami 0.2.0.pre.alpha.1 → 0.2.0.pre.alpha.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d51a4710b34ce6bb8d1a140f7df3fdae00006df8fd23b39c84506297e12f64df
-  data.tar.gz: 18954a7148a4d46c0b3053dadc7ccd534a25c9276eabe317f01274d9a4ce377a
+  metadata.gz: 4adab6a5900c422ff7da10ee21be828ba77c1d7523da39173433ff7749516e73
+  data.tar.gz: d44d102a14b331b1262f692f8479418d8f08557815830899c3fb9be093f34e25
 SHA512:
-  metadata.gz: c3a536625ff7017b56129fd4f151d194240e9dfa4427d3f4d774cb1bb68ef3fd61dd069f7f7b7eef347e90f2339b9596da0ce737df90f1451c6ae81096186b3a
-  data.tar.gz: 178cedf68bfaed0844171fbfd6a935b9c931901f296c59ba922e957ba7caabf825bbd052bf3ce384255df4df7f90a4aa7108ed5d60e08d3102c8d646e4d64b87
+  metadata.gz: 151ad52da0f7b28599a61385974233e109be3a195710f3d2d971783c25202d830cc04b7d85fb8f19c90c6058c2798f0f8e85bc4bc3a81d86003ec242884fb939
+  data.tar.gz: 85e34fbfb79b7cb58352575c5d1cdb18066f4034a427a3d55753992b7f5653d3a348e27c98f593b5db2f56f711fc90755965d5c0470a74f0b467192f6368c833

data/CHANGELOG.md

@@ -7,7 +7,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [v0.2.0-alpha.1] - 2024-10-05
+## [v0.2.0-alpha.3] - 2026-09-06
+
+### Added
+
+- `Phlex::Hanami::Component`, the base class for everything below a view. It reads the same view context a view
+  does, and has neither a layout nor the `call` contract Hanami renders a view through, so Hanami cannot render one
+  by accident.
+- `Phlex::Hanami::Contextual`, the view context and the slice on their own, for a component base class you already
+  have. `Phlex::Hanami::Renderable` includes it and adds the view half.
+- Support for [Phlex kits]. Extend a component namespace with `Phlex::Kit`, include it in a base view, and a view
+  calls its components as methods. A kit registers in the slice container as the module, so `slice["components"]`
+  returns the kit rather than raising `NoMethodError`.
+- `Phlex::Hanami::Testing::ViewHelpers`, for testing a view or a component without a request. `render` renders the
+  instance you give it, `view_context` builds the context an action would have, and `view_request` fakes a request
+  for the session, the flash and the CSRF token.
+- `require "phlex/hanami/rspec"` includes those helpers into every RSpec example group tagged `type: :view`. Under
+  any other framework, require `phlex/hanami/testing` and include the module where your view tests run.
+- RBS signatures for the public API, shipped in `sig`.
+- Documentation for [components](docs/usage/components.md), [testing](docs/usage/testing.md) and
+  [responses](docs/usage/responses.md).
+
+[Phlex kits]: https://www.phlex.fun/components/kits.html
+
+## [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).
 
@@ -15,5 +66,8 @@ Initial alpha release by the new maintainer [@aaronmallen](https://github.com/aa
 
 Initial release, by the previous maintainer [@stephannv](https://github.com/stephannv).
 
-[Unreleased]: https://github.com/aaronmallen/phlex-hanami/compare/0.1.0...HEAD
+[Unreleased]: https://github.com/aaronmallen/phlex-hanami/compare/0.2.0-alpha.3...HEAD
+[v0.2.0-alpha.3]: https://github.com/aaronmallen/phlex-hanami/compare/0.2.0-alpha.2...0.2.0-alpha.3
+[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/lib/phlex/hanami/component.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    # The base class for everything below a view.
+    #
+    # A component is an ordinary Phlex class you render with `render`. It reads the same context a
+    # view does — `path`, `assets`, `content_for`, `flash`, translations — because Phlex shares that
+    # context with every component in the tree, however deep. What it does not have is the half of a
+    # view that belongs to Hanami: no layout, and no `call(context:, **input)` entry point, because
+    # Hanami never calls a component.
+    #
+    # Subclass this, or include {Contextual} into a base class you already have.
+    #
+    # @example
+    #   # app/components/card.rb
+    #   module MyApp
+    #     module Components
+    #       class Card < Phlex::Hanami::Component
+    #         def initialize(post:) = @post = post
+    #
+    #         def view_template
+    #           article do
+    #             h2 { a(href: path(:post, id: @post.id)) { @post.title } }
+    #             yield if block_given?
+    #           end
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    # A component takes the context of whoever renders it, not its own slice's, so one written in
+    # the app namespace works unchanged inside a slice's view.
+    #
+    # @api public
+    # @since 0.2.0
+    class Component < Phlex::HTML
+      include Contextual
+    end
+  end
+end

data/lib/phlex/hanami/context.rb

@@ -17,6 +17,7 @@ module Phlex
 
       # @api private
       # @since 0.2.0
+      #: (singleton(::Hanami::Slice)) -> void
       def self.configure_for_slice(slice)
         extend SliceConfiguredContext.new(slice)
       end
@@ -27,12 +28,20 @@ module Phlex
       #
       # @api public
       # @since 0.2.0
-      attr_reader :inflector
+      attr_reader :inflector #: Dry::Inflector
 
       # @see SliceConfiguredContext#define_new
       #
       # @api private
       # @since 0.2.0
+      #: (
+      #    ?inflector: Dry::Inflector?,
+      #    ?routes: ::Hanami::Slice::RoutesHelper?,
+      #    ?assets: ::Hanami::Assets?,
+      #    ?request: ::Hanami::Action::Request?,
+      #    ?i18n: ::Hanami::Providers::I18n::Backend?,
+      #    **untyped
+      #  ) -> void
       def initialize(inflector: nil, routes: nil, assets: nil, request: nil, i18n: nil, **)
         @inflector = inflector
         @routes = routes
@@ -50,6 +59,7 @@ module Phlex
       #
       # @api public
       # @since 0.2.0
+      #: () -> ::Hanami::Assets
       def assets
         raise ::Hanami::ComponentLoadError, "Assets not available. #{assets_hint}" unless @assets
 
@@ -65,6 +75,7 @@ module Phlex
       #
       # @api public
       # @since 0.2.0
+      #: (Symbol, ?String?) ?{ () -> String } -> String?
       def content_for(key, value = nil)
         if block_given?
           @content_for[key] = yield
@@ -85,6 +96,7 @@ module Phlex
       #
       # @api public
       # @since 0.2.0
+      #: () -> String?
       def csrf_token
         request.session[::Hanami::Action::CSRFProtection::CSRF_TOKEN]
       end
@@ -95,6 +107,7 @@ module Phlex
       #
       # @api public
       # @since 0.2.0
+      #: () -> ::Hanami::Action::Flash
       def flash
         request.flash
       end
@@ -105,6 +118,7 @@ module Phlex
       #
       # @api public
       # @since 0.2.0
+      #: () -> ::Hanami::Providers::I18n::Backend
       def i18n
         raise ::Hanami::ComponentLoadError, "the i18n gem is required to access translations" unless @i18n
 
@@ -113,6 +127,7 @@ module Phlex
 
       # @api private
       # @since 0.2.0
+      #: (self) -> void
       def initialize_copy(source)
         super
         @content_for = source.instance_variable_get(:@content_for).dup
@@ -126,6 +141,7 @@ module Phlex
       #
       # @api public
       # @since 0.2.0
+      #: () -> ::Hanami::Action::Request
       def request
         unless @request
           raise ::Hanami::ComponentLoadError, <<~MESSAGE
@@ -142,6 +158,7 @@ module Phlex
       #
       # @api public
       # @since 0.2.0
+      #: () -> bool
       def request?
         !!@request
       end
@@ -154,6 +171,7 @@ module Phlex
       #
       # @api public
       # @since 0.2.0
+      #: () -> ::Hanami::Slice::RoutesHelper
       def routes
         raise ::Hanami::ComponentLoadError, "the hanami-router gem is required to access routes" unless @routes
 
@@ -166,12 +184,14 @@ module Phlex
       #
       # @api public
       # @since 0.2.0
+      #: () -> ::Hanami::Action::Request::Session
       def session
         request.session
       end
 
       private
 
+      #: () -> String
       def assets_hint
         if ::Hanami.bundled?("hanami-assets")
           "Have you put files into your assets directory?"

data/lib/phlex/hanami/contextual.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Hanami
+    # Gives a Phlex class the Hanami view context and the slice it was defined in.
+    #
+    # This is the half of the integration a component needs: `path`, `assets`, `content_for`,
+    # `flash`, translations and the rest, read off the context Hanami builds for the request.
+    # {Renderable} includes it and adds the `call` contract Hanami's `Response#render` expects;
+    # include this on its own for a class Hanami never calls directly.
+    #
+    # {Component} subclasses it already. Include this instead when you have your own component base
+    # class.
+    #
+    # @example
+    #   module MyApp
+    #     class Component < Phlex::HTML
+    #       include Phlex::Hanami::Contextual
+    #     end
+    #   end
+    #
+    # @api public
+    # @since 0.2.0
+    module Contextual
+      # @api private
+      # @since 0.2.0
+      #: (singleton(::Phlex::SGML)) -> void
+      def self.included(view_class)
+        view_class.extend(::Hanami::SliceConfigurable)
+        view_class.extend(ClassMethods)
+        return unless defined?(::Hanami::Helpers::I18nHelper)
+
+        # Order matters: a module included later sits higher in the lookup chain, so the overrides
+        # have to go in after Hanami's helper, not alongside it in this module.
+        view_class.include(::Hanami::Helpers::I18nHelper)
+        view_class.include(I18nOverrides)
+      end
+
+      # Relative-key resolution for Hanami's i18n helper.
+      #
+      # A Phlex view has no template, so Hanami's implementation — which reads
+      # `_context.current_template_name` — cannot work. Included after `Hanami::Helpers::I18nHelper`
+      # so that it wins: a module included later sits higher in the lookup chain.
+      #
+      # @api private
+      # @since 0.2.0
+      module I18nOverrides
+        private
+
+        # Resolves a relative translation key (`t(".title")`) against the view's own container key, so
+        # `MyApp::Views::Posts::Index` looks up `posts.index.title`.
+        #
+        # Hanami's own implementation uses `_context.current_template_name`, which is hanami-view's
+        # template stack and has no meaning for a Phlex view.
+        #: (String | Symbol) -> (String | Symbol)
+        def _resolve_i18n_key(key)
+          return key unless key.to_s.start_with?(".")
+
+          base = i18n_key_base
+          unless base
+            raise ::I18n::ArgumentError,
+                  "Cannot resolve the relative translation key #{key.inspect} for #{self.class}. " \
+                    "Give the view a name inside a slice, or use an absolute key (without a leading dot)."
+          end
+
+          "#{base}#{key}"
+        end
+
+        # The view's container key, dotted: `MyApp::Views::Posts::Index` in the app slice becomes
+        # `posts.index`. Nil for an anonymous view, or one outside any slice.
+        #: () -> String?
+        def i18n_key_base
+          view_slice = self.class.slice
+          name = self.class.name
+          return nil unless view_slice && name
+
+          view_slice.inflector
+            .underscore(name)
+            .sub(%r{^#{view_slice.slice_name.path}/}, "")
+            .sub(%r{^views/}, "")
+            .tr("/", ".")
+        end
+      end
+
+      # @api public
+      # @since 0.2.0
+      module ClassMethods
+        # @api private
+        # @since 0.2.0
+        #: (singleton(::Hanami::Slice)) -> void
+        def configure_for_slice(slice)
+          extend SliceConfigured.new(slice)
+        end
+
+        # The slice this class belongs to, or nil when it is defined outside a slice namespace.
+        #
+        # A class with no slice still renders: the context comes from whoever is rendering it, not
+        # from the slice. What it loses is the slice-relative half — `t(".title")` has nothing to
+        # resolve against and raises.
+        #
+        # @return [Hanami::Slice, nil]
+        #
+        # @api public
+        # @since 0.2.0
+        #: () -> singleton(::Hanami::Slice)?
+        def slice
+          nil
+        end
+      end
+
+      # The URL for an asset.
+      #
+      # @example
+      #   script(src: asset_url("app.js"))
+      #
+      # @param source [String] the asset's source path
+      #
+      # @return [String] the URL
+      #
+      # @api public
+      # @since 0.2.0
+      #: (String) -> String
+      def asset_url(source)
+        assets[source].url
+      end
+
+      # The slice's assets.
+      #
+      # @api public
+      # @since 0.2.0
+      #: () -> ::Hanami::Assets
+      def assets
+        hanami_context.assets
+      end
+
+      # Stores a string of markup for later use, or reads back what was stored.
+      #
+      # @api public
+      # @since 0.2.0
+      #: (Symbol, ?String?) ?{ () -> String } -> String?
+      def content_for(...)
+        hanami_context.content_for(...)
+      end
+
+      # The current request's CSRF token.
+      #
+      # @return [String]
+      #
+      # @api public
+      # @since 0.2.0
+      #: () -> String?
+      def csrf_token
+        hanami_context.csrf_token
+      end
+
+      # The flash hash for the current request.
+      #
+      # @api public
+      # @since 0.2.0
+      #: () -> ::Hanami::Action::Flash
+      def flash
+        hanami_context.flash
+      end
+
+      # The Hanami view context for this render.
+      #
+      # Read from Phlex's user context, which is shared with every component in the render tree, so
+      # a component nested any number of levels deep sees the same context.
+      #
+      # @return [Object] a `Hanami::View::Context` when hanami-view is bundled, otherwise a {Context}
+      #
+      # @raise [MissingContextError] when the view was rendered without a context
+      #
+      # @api public
+      # @since 0.2.0
+      #: () -> (::Hanami::View::Context | Context)
+      def hanami_context
+        context[CONTEXT_KEY] || raise(MissingContextError, self.class)
+      end
+
+      # Whether a Hanami view context is available.
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      # @since 0.2.0
+      #: () -> bool
+      def hanami_context?
+        !context[CONTEXT_KEY].nil?
+      end
+
+      # The slice's i18n backend.
+      #
+      # @api public
+      # @since 0.2.0
+      #: () -> ::Hanami::Providers::I18n::Backend
+      def i18n
+        hanami_context.i18n
+      end
+
+      # The path for a named route.
+      #
+      # @example
+      #   a(href: path(:posts)) { "Posts" }
+      #
+      # @return [String]
+      #
+      # @api public
+      # @since 0.2.0
+      #: (*untyped, **untyped) -> String
+      def path(...)
+        routes.path(...)
+      end
+
+      # The current request.
+      #
+      # @return [Hanami::Action::Request]
+      #
+      # @api public
+      # @since 0.2.0
+      #: () -> ::Hanami::Action::Request
+      def request
+        hanami_context.request
+      end
+
+      # Whether the view is being rendered from within a request.
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      # @since 0.2.0
+      #: () -> bool
+      def request?
+        hanami_context? && hanami_context.request?
+      end
+
+      # The app's routes helper.
+      #
+      # @return [Hanami::Slice::RoutesHelper]
+      #
+      # @api public
+      # @since 0.2.0
+      #: () -> ::Hanami::Slice::RoutesHelper
+      def routes
+        hanami_context.routes
+      end
+
+      # The session for the current request.
+      #
+      # @api public
+      # @since 0.2.0
+      #: () -> ::Hanami::Action::Request::Session
+      def session
+        hanami_context.session
+      end
+
+      # The slice this class belongs to.
+      #
+      # @return [Hanami::Slice, nil]
+      #
+      # @api public
+      # @since 0.2.0
+      #: () -> singleton(::Hanami::Slice)?
+      def slice
+        self.class.slice
+      end
+
+      # The full URL for a named route.
+      #
+      # Hanami's routes helper returns a `URI`; Phlex writes strings, and rejects anything else as
+      # an attribute value, so this hands back the string.
+      #
+      # @example
+      #   a(href: url(:posts)) { "Posts" }
+      #
+      # @return [String]
+      #
+      # @api public
+      # @since 0.2.0
+      #: (*untyped, **untyped) -> String
+      def url(...)
+        routes.url(...).to_s
+      end
+
+      private
+
+      # Hanami's helper modules reach for the view context under this name.
+      #: () -> (::Hanami::View::Context | Context)
+      def _context
+        hanami_context
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# 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
+      #: (singleton(::Hanami::Mailer), singleton(::Phlex::SGML)) -> void
+      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

@@ -9,6 +9,7 @@ module Phlex
     class MissingContextError < Error
       # @api private
       # @since 0.2.0
+      #: (singleton(::Phlex::SGML)) -> void
       def initialize(view_class)
         super(<<~MESSAGE)
           #{view_class} was rendered without a Hanami view context.

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

@@ -0,0 +1,27 @@
+# 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
+      #: (singleton(::Phlex::SGML)) -> void
+      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