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

data/lib/phlex/hanami/testing.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "phlex/hanami"
+require "rack/mock_request"
+
+module Phlex
+  module Hanami
+    # Test support for view and component specs, whatever the test framework.
+    #
+    # A Phlex view is an ordinary Ruby object, so most of it needs no help: build one and call it.
+    # What it does need is a view context, because a view that reaches for `path`, `assets` or
+    # `flash` reads them off the context Hanami builds per request. {ViewHelpers} gives you that
+    # context without a request, and a fake request when the view wants one.
+    #
+    # `require "phlex/hanami/rspec"` includes the helpers into every RSpec example group tagged
+    # `type: :view`. Under any other framework, require this file and include the module yourself:
+    #
+    #     # test/support/phlex.rb
+    #     require "phlex/hanami/testing"
+    #
+    #     class Hanami::Minitest::Test
+    #       include Phlex::Hanami::Testing::ViewHelpers
+    #     end
+    #
+    # @api public
+    # @since 0.2.0
+    module Testing
+      # Renders a view or component, and builds what a view needs to render.
+      #
+      # Nothing here is tied to a test framework. Include it into whichever class or example group
+      # your view tests run in.
+      #
+      # @example
+      #   class PostIndexTest < Hanami::Minitest::Test
+      #     include Phlex::Hanami::Testing::ViewHelpers
+      #
+      #     test "lists the posts" do
+      #       assert_includes render(MyApp::Views::Posts::Index.new(posts: [post])), "<h1>Posts</h1>"
+      #     end
+      #   end
+      #
+      # @api public
+      # @since 0.2.0
+      module ViewHelpers
+        # Renders a view or component and returns the markup.
+        #
+        # Renders the instance you pass, so no layout is applied. Call the class instead
+        # (`described_class.call(context: view_context, **input)`) to render a view inside its
+        # layout, the way Hanami does.
+        #
+        # The context comes from the view's own slice, so routes, assets and translations are the
+        # real ones. Pass `request:` for a view that reads the session, the flash or the CSRF
+        # token, or `context:` to supply the whole context yourself.
+        #
+        # @example A component that takes a block
+        #   render(Card.new(title: "Hello")) { "body" }
+        #
+        # @param view [Phlex::SGML] the view or component instance
+        # @param context [Object, nil] a view context, built from the view's slice when omitted
+        # @param request [Hanami::Action::Request, nil] a request for the context to carry
+        #
+        # @return [String] the rendered markup
+        #
+        # @api public
+        # @since 0.2.0
+        #: (
+        #    ::Phlex::SGML,
+        #    ?context: (::Hanami::View::Context | Context)?,
+        #    ?request: ::Hanami::Action::Request?
+        #  ) ?{ (?) -> untyped } -> String
+        def render(view, context: nil, request: nil, &)
+          context ||= view_context(slice: slice_for(view), request: request)
+
+          view.call(context: { CONTEXT_KEY => context }, &)
+        end
+
+        # Builds a view context.
+        #
+        # Uses the same context class an action would: a `Hanami::View::Context` subclass when
+        # hanami-view is bundled, otherwise a {Phlex::Hanami::Context} subclass. Either way the
+        # slice's own routes, assets, inflector and i18n backend are injected.
+        #
+        # Falls back to a bare {Phlex::Hanami::Context} when there is no slice to build from. That
+        # context answers `content_for` and raises a helpful error for anything needing a slice or
+        # a request, which is what a view rendered outside an app should see.
+        #
+        # @param slice [Hanami::Slice, nil] the slice to build from, defaulting to the app
+        # @param request [Hanami::Action::Request, nil] a request for the context to carry
+        # @param options [Hash] passed on to the context's initializer
+        #
+        # @return [Object] the context
+        #
+        # @api public
+        # @since 0.2.0
+        #: (
+        #    ?slice: singleton(::Hanami::Slice)?,
+        #    ?request: ::Hanami::Action::Request?,
+        #    **untyped
+        #  ) -> (::Hanami::View::Context | Context)
+        def view_context(slice: nil, request: nil, **)
+          slice ||= ::Hanami.app if ::Hanami.app?
+          context_class = slice ? Extensions::Slice.view_context_class(slice) : Context
+
+          context_class.new(request: request, **)
+        end
+
+        # Builds a request for a view to read, without running an action.
+        #
+        # Sessions are always enabled on it, so `session`, `flash` and `csrf_token` answer rather
+        # than raising `Hanami::Action::MissingSessionError`.
+        #
+        # @example
+        #   render(described_class.new, request: view_request("/posts", flash: { alert: "Nope" }))
+        #
+        # @param path [String] the request path
+        # @param csrf_token [String, nil] the token `csrf_token` returns
+        # @param flash [Hash] the flash for this request
+        # @param session [Hash] the session, keyed by String
+        # @param options [Hash] passed on to `Rack::MockRequest.env_for`
+        #
+        # @return [Hanami::Action::Request]
+        #
+        # @api public
+        # @since 0.2.0
+        #: (
+        #    ?String,
+        #    ?csrf_token: String?,
+        #    ?flash: Hash[Symbol | String, untyped],
+        #    ?session: Hash[Symbol | String, untyped],
+        #    **untyped
+        #  ) -> ::Hanami::Action::Request
+        def view_request(path = "/", csrf_token: nil, flash: {}, session: {}, **)
+          env = ::Rack::MockRequest.env_for(path, **)
+          env["rack.session"] = session.transform_keys(&:to_s)
+          env["rack.session"][::Hanami::Action::Flash::KEY] = flash unless flash.empty?
+          env["rack.session"][::Hanami::Action::CSRFProtection::CSRF_TOKEN.to_s] = csrf_token if csrf_token
+
+          ::Hanami::Action::Request.new(
+            env: env,
+            params: ::Hanami::Action::Params.new(env: env),
+            session_enabled: true,
+          )
+        end
+
+        private
+
+        # The slice a view belongs to. Nil for a plain Phlex class, which has no `slice` at all,
+        # and for a Renderable one defined outside a slice namespace.
+        #: (::Phlex::SGML) -> singleton(::Hanami::Slice)?
+        def slice_for(view)
+          view.class.slice if view.class.respond_to?(:slice)
+        end
+      end
+    end
+  end
+end

data/lib/phlex/hanami.rb

@@ -36,7 +36,9 @@ Zeitwerk::Loader.new.tap do |loader|
   loader.tag = "phlex-hanami"
   loader.push_dir(lib_dir, namespace: Phlex::Hanami)
   loader.collapse(File.join(lib_dir, "errors"))
-  loader.ignore(__FILE__)
+  # Test support is opt in, so nothing here should autoload it. `rspec.rb` also has no constant of
+  # its own for Zeitwerk to hang an autoload on.
+  loader.ignore(__FILE__, File.join(lib_dir, "rspec.rb"), File.join(lib_dir, "testing.rb"))
 end.setup
 
 # Installs the integration. Referencing the constant is what autoloads it, so this cannot move into

data/sig/external/dry.rbs

@@ -0,0 +1,9 @@
+module Dry
+  class Inflector
+    def camelize: (String) -> String
+
+    def constantize: (String) -> untyped
+
+    def underscore: (String) -> String
+  end
+end

data/sig/external/hanami.rbs

@@ -0,0 +1,77 @@
+module Hanami
+  def self.app: () -> singleton(Slice)
+
+  def self.app?: () -> bool
+
+  def self.bundled?: (String) -> bool
+
+  class Error < StandardError
+  end
+
+  class ComponentLoadError < Error
+  end
+
+  module SliceConfigurable
+  end
+
+  # A slice is used as a class throughout, never instantiated, so every signature that takes one
+  # says `singleton(Hanami::Slice)`.
+  class Slice
+    def self.app: () -> singleton(Slice)
+
+    def self.[]: (String) -> untyped
+
+    def self.inflector: () -> Dry::Inflector
+
+    def self.key?: (String) -> bool
+
+    def self.namespace: () -> Module
+
+    def self.slice_name: () -> SliceName
+
+    class RoutesHelper
+      def path: (*untyped, **untyped) -> String
+
+      def url: (*untyped, **untyped) -> URI::Generic
+    end
+  end
+
+  class SliceName
+    def name: () -> String
+
+    def path: () -> String
+  end
+
+  class Assets
+    def []: (String) -> _Asset
+  end
+
+  interface _Asset
+    def url: () -> String
+  end
+
+  class Action
+    class Flash
+    end
+
+    class Request
+      class Session
+        def []: (String | Symbol) -> untyped
+      end
+
+      def flash: () -> Flash
+
+      def session: () -> Session
+    end
+  end
+
+  class Mailer
+  end
+
+  module Providers
+    class I18n
+      class Backend
+      end
+    end
+  end
+end

data/sig/external/hanami_view.rbs

@@ -0,0 +1,9 @@
+# hanami-view is optional. When it is bundled Hanami builds the view context from its class rather
+# than from ours, so a view's context is one or the other and every signature naming a context says
+# so. Declaring the class here costs nothing when the gem is absent: RBS is never loaded at runtime.
+module Hanami
+  class View
+    class Context
+    end
+  end
+end

data/sig/external/phlex.rbs

@@ -0,0 +1,16 @@
+module Phlex
+  class SGML
+    def self.call: (?String, ?context: Hash[untyped, untyped], ?fragments: Array[String]?) ?{ (?) -> untyped } -> String
+
+    def call: (?String, ?context: Hash[untyped, untyped], ?fragments: Array[String]?) ?{ (?) -> untyped } -> String
+
+    def context: () -> Hash[untyped, untyped]
+
+    def raw: (untyped) -> void
+
+    def safe: (String) -> untyped
+  end
+
+  class HTML < SGML
+  end
+end

data/sig/phlex/hanami/component.rbs

@@ -0,0 +1,9 @@
+# Generated from lib/phlex/hanami/component.rb with RBS::Inline
+
+module Phlex
+  module Hanami
+    class Component < Phlex::HTML
+      include Contextual
+    end
+  end
+end

data/sig/phlex/hanami/context.rbs

@@ -0,0 +1,39 @@
+# Generated from lib/phlex/hanami/context.rb with RBS::Inline
+
+module Phlex
+  module Hanami
+    class Context
+      extend ::Hanami::SliceConfigurable
+
+      def self.configure_for_slice: (singleton(::Hanami::Slice)) -> void
+
+      attr_reader inflector: Dry::Inflector
+
+      def initialize: (?inflector: Dry::Inflector?, ?routes: ::Hanami::Slice::RoutesHelper?, ?assets: ::Hanami::Assets?, ?request: ::Hanami::Action::Request?, ?i18n: ::Hanami::Providers::I18n::Backend?, **untyped) -> void
+
+      def assets: () -> ::Hanami::Assets
+
+      def content_for: (Symbol, ?String?) ?{ () -> String } -> String?
+
+      def csrf_token: () -> String?
+
+      def flash: () -> ::Hanami::Action::Flash
+
+      def i18n: () -> ::Hanami::Providers::I18n::Backend
+
+      def initialize_copy: (self) -> void
+
+      def request: () -> ::Hanami::Action::Request
+
+      def request?: () -> bool
+
+      def routes: () -> ::Hanami::Slice::RoutesHelper
+
+      def session: () -> ::Hanami::Action::Request::Session
+
+      private
+
+      def assets_hint: () -> String
+    end
+  end
+end

data/sig/phlex/hanami/contextual.rbs

@@ -0,0 +1,57 @@
+# Generated from lib/phlex/hanami/contextual.rb with RBS::Inline
+
+module Phlex
+  module Hanami
+    module Contextual
+      def self.included: (singleton(::Phlex::SGML)) -> void
+
+      module I18nOverrides
+        private
+
+        def _resolve_i18n_key: (String | Symbol) -> (String | Symbol)
+
+        def i18n_key_base: () -> String?
+      end
+
+      module ClassMethods
+        def configure_for_slice: (singleton(::Hanami::Slice)) -> void
+
+        def slice: () -> singleton(::Hanami::Slice)?
+      end
+
+      def asset_url: (String) -> String
+
+      def assets: () -> ::Hanami::Assets
+
+      def content_for: (Symbol, ?String?) ?{ () -> String } -> String?
+
+      def csrf_token: () -> String?
+
+      def flash: () -> ::Hanami::Action::Flash
+
+      def hanami_context: () -> (::Hanami::View::Context | Context)
+
+      def hanami_context?: () -> bool
+
+      def i18n: () -> ::Hanami::Providers::I18n::Backend
+
+      def path: (*untyped, **untyped) -> String
+
+      def request: () -> ::Hanami::Action::Request
+
+      def request?: () -> bool
+
+      def routes: () -> ::Hanami::Slice::RoutesHelper
+
+      def session: () -> ::Hanami::Action::Request::Session
+
+      def slice: () -> singleton(::Hanami::Slice)?
+
+      def url: (*untyped, **untyped) -> String
+
+      private
+
+      def _context: () -> (::Hanami::View::Context | Context)
+    end
+  end
+end

data/sig/phlex/hanami/errors/error.rbs

@@ -0,0 +1,8 @@
+# Generated from lib/phlex/hanami/errors/error.rb with RBS::Inline
+
+module Phlex
+  module Hanami
+    class Error < StandardError
+    end
+  end
+end

data/sig/phlex/hanami/errors/mailer_view_error.rbs

@@ -0,0 +1,9 @@
+# Generated from lib/phlex/hanami/errors/mailer_view_error.rb with RBS::Inline
+
+module Phlex
+  module Hanami
+    class MailerViewError < Error
+      def initialize: (singleton(::Hanami::Mailer), singleton(::Phlex::SGML)) -> void
+    end
+  end
+end

data/sig/phlex/hanami/errors/missing_context_error.rbs

@@ -0,0 +1,9 @@
+# Generated from lib/phlex/hanami/errors/missing_context_error.rb with RBS::Inline
+
+module Phlex
+  module Hanami
+    class MissingContextError < Error
+      def initialize: (singleton(::Phlex::SGML)) -> void
+    end
+  end
+end

data/sig/phlex/hanami/errors/relative_path_error.rbs

@@ -0,0 +1,9 @@
+# Generated from lib/phlex/hanami/errors/relative_path_error.rb with RBS::Inline
+
+module Phlex
+  module Hanami
+    class RelativePathError < Error
+      def initialize: (singleton(::Phlex::SGML)) -> void
+    end
+  end
+end

data/sig/phlex/hanami/extensions/mailer.rbs

@@ -0,0 +1,25 @@
+# Generated from lib/phlex/hanami/extensions/mailer.rb with RBS::Inline
+
+module Phlex
+  module Hanami
+    module Extensions
+      module Mailer
+        def self.install: () -> void
+
+        module ClassMethods
+          def configure_for_slice: (singleton(::Hanami::Slice)) -> void
+
+          def phlex_view: () -> singleton(::Phlex::SGML)?
+
+          def slice: () -> singleton(::Hanami::Slice)?
+
+          private
+
+          def view_name: (singleton(::Hanami::Slice)) -> String
+        end
+
+        def view: () -> untyped
+      end
+    end
+  end
+end

data/sig/phlex/hanami/extensions/slice.rbs

@@ -0,0 +1,21 @@
+# Generated from lib/phlex/hanami/extensions/slice.rb with RBS::Inline
+
+module Phlex
+  module Hanami
+    module Extensions
+      module Slice
+        COMPONENT_INSTANCE: ^(untyped, *untyped, **untyped) -> untyped
+
+        def prepare: (?String?) -> untyped
+
+        def self.define_view_context: (singleton(::Hanami::Slice)) -> singleton(Context)?
+
+        def self.register_phlex_components: (singleton(::Hanami::Slice)) -> void
+
+        def self.view_context_class: (singleton(::Hanami::Slice)) -> (singleton(::Hanami::View::Context) | singleton(Context))
+
+        private def self.views_namespace: (singleton(::Hanami::Slice)) -> Module
+      end
+    end
+  end
+end

data/sig/phlex/hanami/helpers.rbs

@@ -0,0 +1,13 @@
+# Generated from lib/phlex/hanami/helpers.rb with RBS::Inline
+
+module Phlex
+  module Hanami
+    module Helpers
+      OVERRIDDEN_METHODS: Hash[Symbol, UnboundMethod]
+
+      PhlexMethods: Module
+
+      def self.included: (singleton(::Phlex::SGML)) -> void
+    end
+  end
+end

data/sig/phlex/hanami/layout.rbs

@@ -0,0 +1,9 @@
+# Generated from lib/phlex/hanami/layout.rb with RBS::Inline
+
+module Phlex
+  module Hanami
+    class Layout < Phlex::HTML
+      include Renderable
+    end
+  end
+end

data/sig/phlex/hanami/mailer/layout.rbs

@@ -0,0 +1,11 @@
+# Generated from lib/phlex/hanami/mailer/layout.rb with RBS::Inline
+
+module Phlex
+  module Hanami
+    module Mailer
+      class Layout < Phlex::HTML
+        include Renderable
+      end
+    end
+  end
+end

data/sig/phlex/hanami/mailer/renderable.rbs

@@ -0,0 +1,27 @@
+# Generated from lib/phlex/hanami/mailer/renderable.rb with RBS::Inline
+
+module Phlex
+  module Hanami
+    module Mailer
+      module Renderable
+        def self.included: (singleton(::Phlex::SGML)) -> void
+
+        module ClassMethods
+          def call: (?context: (::Hanami::View::Context | Context)?, ?format: Symbol | String, **untyped) -> String
+
+          private
+
+          def default_layout: () -> singleton(::Phlex::SGML)?
+
+          def mail_context: () -> (::Hanami::View::Context | Context)?
+        end
+
+        module MailMethods
+          def path: (*untyped, **untyped) -> bot
+
+          def text_body: (String) -> String
+        end
+      end
+    end
+  end
+end

data/sig/phlex/hanami/mailer/text.rbs

@@ -0,0 +1,47 @@
+# Generated from lib/phlex/hanami/mailer/text.rb with RBS::Inline
+
+module Phlex
+  module Hanami
+    module Mailer
+      class Text
+        BLOCK_ELEMENTS: Array[String]
+
+        BLOCK_PATTERN: Regexp
+
+        ENTITIES: Hash[String, String]
+
+        ENTITY_PATTERN: Regexp
+
+        LINK_CLOSE: String
+
+        LINK_OPEN: String
+
+        def self.call: (_ToS) -> String
+
+        private def self.anchor_text: (String, String) -> String
+
+        private def self.body_of: (String) -> String
+
+        private def self.expand_anchors: (String) -> String
+
+        private def self.expand_blocks: (String) -> String
+
+        private def self.expand_breaks: (String) -> String
+
+        private def self.expand_list_items: (String) -> String
+
+        private def self.href_in: (String) -> String
+
+        private def self.restore_links: (String) -> String
+
+        private def self.strip_hidden_elements: (String) -> String
+
+        private def self.strip_tags: (String) -> String
+
+        private def self.tidy: (String) -> String
+
+        private def self.unescape: (String) -> String
+      end
+    end
+  end
+end

data/sig/phlex/hanami/mailer/view.rbs

@@ -0,0 +1,11 @@
+# Generated from lib/phlex/hanami/mailer/view.rb with RBS::Inline
+
+module Phlex
+  module Hanami
+    module Mailer
+      class View < Phlex::HTML
+        include Renderable
+      end
+    end
+  end
+end

data/sig/phlex/hanami/mailer.rbs

@@ -0,0 +1,8 @@
+# Generated from lib/phlex/hanami/mailer.rb with RBS::Inline
+
+module Phlex
+  module Hanami
+    module Mailer
+    end
+  end
+end

data/sig/phlex/hanami/renderable.rbs

@@ -0,0 +1,27 @@
+# Generated from lib/phlex/hanami/renderable.rb with RBS::Inline
+
+module Phlex
+  module Hanami
+    module Renderable
+      KEYWORD_TYPES: Array[Symbol]
+
+      UNSET: Object
+
+      def self.included: (singleton(::Phlex::SGML)) -> void
+
+      module ClassMethods
+        def call: (?context: (::Hanami::View::Context | Context)?, **untyped) -> String
+
+        def configured_layout: () -> (singleton(::Phlex::SGML) | Object | nil)
+
+        def layout: (?singleton(::Phlex::SGML)?) -> singleton(::Phlex::SGML)?
+
+        private
+
+        def accepted_input: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+
+        def default_layout: () -> singleton(::Phlex::SGML)?
+      end
+    end
+  end
+end

data/sig/phlex/hanami/rspec.rbs

@@ -0,0 +1 @@
+# Generated from lib/phlex/hanami/rspec.rb with RBS::Inline

data/sig/phlex/hanami/slice_configured.rbs

@@ -0,0 +1,19 @@
+# Generated from lib/phlex/hanami/slice_configured.rb with RBS::Inline
+
+module Phlex
+  module Hanami
+    class SliceConfigured < Module
+      attr_reader slice: singleton(::Hanami::Slice)
+
+      def initialize: (singleton(::Hanami::Slice)) -> void
+
+      def extended: (singleton(::Phlex::SGML) | singleton(::Hanami::Mailer)) -> void
+
+      def inspect: () -> String
+
+      private
+
+      def define_slice: () -> void
+    end
+  end
+end