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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb2ded5cb201e8636daeba76f21fc25b297899eba517ce428d6fcc41450460f9
-  data.tar.gz: f8935646735d5d5e52faf6c48b5713dae2f4169c02e8162fc4356c32e5cf09bd
+  metadata.gz: 4adab6a5900c422ff7da10ee21be828ba77c1d7523da39173433ff7749516e73
+  data.tar.gz: d44d102a14b331b1262f692f8479418d8f08557815830899c3fb9be093f34e25
 SHA512:
-  metadata.gz: 396360b1808f053b39c29047103c6f860c46ac6bf436890a483848c63639c1e382fc0ad34eefb61f58335a4d158783349670c2b0ee30a421473737c5111e2abf
-  data.tar.gz: 84fbc91b5c45c6ece40da01070cd64bd9b2702cbc19c10c1ba8eeb3d27cc7aab57e3e60434305b18021dc980cc0a1fff983a051d5cce33b09b200fd87667db52
+  metadata.gz: 151ad52da0f7b28599a61385974233e109be3a195710f3d2d971783c25202d830cc04b7d85fb8f19c90c6058c2798f0f8e85bc4bc3a81d86003ec242884fb939
+  data.tar.gz: 85e34fbfb79b7cb58352575c5d1cdb18066f4034a427a3d55753992b7f5653d3a348e27c98f593b5db2f56f711fc90755965d5c0470a74f0b467192f6368c833

data/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
@@ -43,7 +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.2.0-alpha.2...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

@@ -12,6 +12,7 @@ module Phlex
     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.

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

@@ -12,6 +12,7 @@ module Phlex
     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.

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

@@ -21,6 +21,7 @@ module Phlex
         #
         # @api private
         # @since 0.2.0
+        #: () -> void
         def self.install
           ::Hanami::Mailer.prepend(self)
           ::Hanami::Mailer.singleton_class.prepend(ClassMethods)
@@ -31,6 +32,7 @@ module Phlex
         module ClassMethods
           # @api private
           # @since 0.2.0
+          #: (singleton(::Hanami::Slice)) -> void
           def configure_for_slice(slice)
             super
             extend SliceConfigured.new(slice)
@@ -49,6 +51,7 @@ module Phlex
           #
           # @api private
           # @since 0.2.0
+          #: () -> singleton(::Phlex::SGML)?
           def phlex_view
             mailer_slice = slice
             return nil unless mailer_slice && name
@@ -69,12 +72,14 @@ module Phlex
           #
           # @api private
           # @since 0.2.0
+          #: () -> singleton(::Hanami::Slice)?
           def slice
             nil
           end
 
           private
 
+          #: (singleton(::Hanami::Slice)) -> String
           def view_name(mailer_slice)
             mailer_slice.inflector
               .underscore(name)
@@ -93,6 +98,7 @@ module Phlex
         #
         # @api private
         # @since 0.2.0
+        #: () -> untyped
         def view
           @view || self.class.phlex_view || super
         end

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

@@ -18,26 +18,31 @@ module Phlex
       # @api private
       # @since 0.2.0
       module Slice
-        # Returns Phlex classes as classes, and everything else as the loader would.
+        # Returns Phlex classes and kits as themselves, 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`.
         #
+        # A kit is a module rather than a class, and the default loader calls `new` on whatever it
+        # resolves, so `slice["components"]` would raise `NoMethodError` for one. Registering it as
+        # the module hands back the thing a kit is for.
+        #
         # @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
+          if (constant.is_a?(Class) && constant < Phlex::SGML) || constant.is_a?(Phlex::Kit)
             constant
           else
             component.loader.call(component, *args, **kwargs)
           end
-        }
+        } #: ^(untyped, *untyped, **untyped) -> untyped
 
         # @api private
         # @since 0.2.0
+        #: (?String?) -> untyped
         def prepare(provider_name = nil)
           result = super
 
@@ -59,6 +64,7 @@ module Phlex
           #
           # @api private
           # @since 0.2.0
+          #: (singleton(::Hanami::Slice)) -> singleton(Context)?
           def define_view_context(slice)
             return if ::Hanami.bundled?("hanami-view")
 
@@ -78,6 +84,7 @@ module Phlex
           #
           # @api private
           # @since 0.2.0
+          #: (singleton(::Hanami::Slice)) -> void
           def register_phlex_components(slice)
             component_dirs = slice.container.config.component_dirs
             return if component_dirs.configured?(:instance)
@@ -95,6 +102,7 @@ module Phlex
           #
           # @api private
           # @since 0.2.0
+          #: (singleton(::Hanami::Slice)) -> (singleton(::Hanami::View::Context) | singleton(Context))
           def view_context_class(slice)
             return ::Hanami::Extensions::View::Context.context_class(slice) if ::Hanami.bundled?("hanami-view")
 
@@ -103,6 +111,7 @@ module Phlex
 
           private
 
+          #: (singleton(::Hanami::Slice)) -> Module
           def views_namespace(slice)
             if slice.namespace.const_defined?(:Views, false)
               slice.namespace.const_get(:Views, false)

data/lib/phlex/hanami/helpers.rb

@@ -46,7 +46,7 @@ module Phlex
       OVERRIDDEN_METHODS = {
         raw: Phlex::SGML.instance_method(:raw),
         tag: Phlex::HTML.instance_method(:tag),
-      }.freeze
+      }.freeze #: Hash[Symbol, UnboundMethod]
 
       # Phlex's implementations, mixed back in over Hanami's.
       #
@@ -56,10 +56,11 @@ module Phlex
         OVERRIDDEN_METHODS.each do |name, method|
           define_method(name) { |*args, **options, &block| method.bind_call(self, *args, **options, &block) }
         end
-      end
+      end #: Module
 
       # @api private
       # @since 0.2.0
+      #: (singleton(::Phlex::SGML)) -> void
       def self.included(view_class)
         view_class.include(::Hanami::Extensions::View::StandardHelpers)
         view_class.include(PhlexMethods)