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

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)

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

@@ -22,6 +22,7 @@ module Phlex
       module Renderable
         # @api private
         # @since 0.2.0
+        #: (singleton(::Phlex::SGML)) -> void
         def self.included(view_class)
           view_class.include(::Phlex::Hanami::Renderable)
 
@@ -48,6 +49,7 @@ module Phlex
           #
           # @api public
           # @since 0.2.0
+          #: (?context: (::Hanami::View::Context | Context)?, ?format: Symbol | String, **untyped) -> String
           def call(context: nil, format: :html, **input)
             html = super(context: context || mail_context, **input)
             return html unless format.to_s == "text"
@@ -62,6 +64,7 @@ module Phlex
           # The web layout is the wrong one for an email — it carries the stylesheets, scripts and
           # page chrome no mail client wants — so mail looks for its own, and renders without a
           # layout when the slice has none.
+          #: () -> singleton(::Phlex::SGML)?
           def default_layout
             return nil unless slice
             return nil unless slice.namespace.const_defined?(:Views, false)
@@ -78,6 +81,7 @@ module Phlex
           # The same class an action would be given, so a view reads the same in both places. What
           # a request would have filled in — `request`, `session`, `flash`, `csrf_token` — is
           # missing, and the context says so when a view reaches for it.
+          #: () -> (::Hanami::View::Context | Context)?
           def mail_context
             return nil unless slice
 
@@ -99,6 +103,7 @@ module Phlex
           #
           # @api public
           # @since 0.2.0
+          #: (*untyped, **untyped) -> bot
           def path(*, **)
             raise RelativePathError, self.class
           end
@@ -119,6 +124,7 @@ module Phlex
           #
           # @api public
           # @since 0.2.0
+          #: (String) -> String
           def text_body(html)
             Text.call(html)
           end

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

@@ -21,11 +21,11 @@ module Phlex
         # @since 0.2.0
         BLOCK_ELEMENTS = %w[
           article blockquote div footer h1 h2 h3 h4 h5 h6 header hr li ol p section table td tr ul
-        ].freeze
+        ].freeze #: Array[String]
 
         # @api private
         # @since 0.2.0
-        BLOCK_PATTERN = %r{</?(?:#{BLOCK_ELEMENTS.join('|')})\b[^>]*>}i
+        BLOCK_PATTERN = %r{</?(?:#{BLOCK_ELEMENTS.join('|')})\b[^>]*>}i #: Regexp
 
         # The entities Phlex escapes, and the characters they stand for.
         #
@@ -39,22 +39,22 @@ module Phlex
           "&lt;" => "<",
           "&nbsp;" => " ",
           "&quot;" => '"',
-        }.freeze
+        }.freeze #: Hash[String, String]
 
         # @api private
         # @since 0.2.0
-        ENTITY_PATTERN = /&(?:amp|apos|gt|lt|nbsp|quot|#39);/
+        ENTITY_PATTERN = /&(?:amp|apos|gt|lt|nbsp|quot|#39);/ #: Regexp
 
         # Stand in for the angle brackets around a URL until the tags are gone, so that stripping
         # tags does not eat the link the converter has just written.
         #
         # @api private
         # @since 0.2.0
-        LINK_CLOSE = "\u0011"
+        LINK_CLOSE = "\u0011" #: String
 
         # @api private
         # @since 0.2.0
-        LINK_OPEN = "\u0010"
+        LINK_OPEN = "\u0010" #: String
 
         class << self
           # Converts rendered HTML to plain text.
@@ -65,6 +65,7 @@ module Phlex
           #
           # @api public
           # @since 0.2.0
+          #: (_ToS) -> String
           def call(html)
             text = body_of(html.to_s)
             text = strip_hidden_elements(text)
@@ -80,6 +81,7 @@ module Phlex
           private
 
           # `Label <https://example.com/path>`, or one of the two when the other adds nothing.
+          #: (String, String) -> String
           def anchor_text(attributes, inner)
             url = href_in(attributes)
             label = strip_tags(inner).gsub(/\s+/, " ").strip
@@ -89,18 +91,24 @@ module Phlex
             "#{label} #{LINK_OPEN}#{url}#{LINK_CLOSE}"
           end
 
+          #: (String) -> String
           def body_of(html) = html[%r{<body\b[^>]*>(.*?)</body>}mi, 1] || html
 
+          #: (String) -> String
           def expand_anchors(html)
             html.gsub(%r{<a\b([^>]*)>(.*?)</a>}mi) { anchor_text(Regexp.last_match(1), Regexp.last_match(2)) }
           end
 
+          #: (String) -> String
           def expand_blocks(html) = html.gsub(BLOCK_PATTERN, "\n\n")
 
+          #: (String) -> String
           def expand_breaks(html) = html.gsub(%r{<br\b[^>]*/?>}i, "\n")
 
+          #: (String) -> String
           def expand_list_items(html) = html.gsub(%r{</li\s*>}i, "").gsub(/<li\b[^>]*>/i, "\n- ")
 
+          #: (String) -> String
           def href_in(attributes)
             match = attributes.match(/\bhref\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))/i)
             return "" unless match
@@ -108,14 +116,19 @@ module Phlex
             (match[1] || match[2] || match[3]).to_s.strip
           end
 
+          #: (String) -> String
           def restore_links(text) = text.gsub(LINK_OPEN, "<").gsub(LINK_CLOSE, ">")
 
+          #: (String) -> String
           def strip_hidden_elements(html) = html.gsub(%r{<(head|style|script)\b[^>]*>.*?</\1\s*>}mi, "")
 
+          #: (String) -> String
           def strip_tags(html) = html.gsub(/<!--.*?-->/m, "").gsub(/<[^>]*>/, "")
 
+          #: (String) -> String
           def tidy(text) = text.gsub(/[ \t]+/, " ").gsub(/[ \t]+$/, "").gsub(/\n{3,}/, "\n\n").strip
 
+          #: (String) -> String
           def unescape(text) = text.gsub(ENTITY_PATTERN) { ENTITIES.fetch(Regexp.last_match(0)) }
         end
       end

data/lib/phlex/hanami/renderable.rb

@@ -5,8 +5,11 @@ module Phlex
     # Makes a Phlex class renderable by Hanami.
     #
     # Include this into an existing `Phlex::SGML` subclass, or subclass {View}, which includes it
-    # already. It gives the class the `call` contract Hanami's `Response#render` expects, per-slice
-    # configuration, and access to the request's view context.
+    # already. It gives the class the `call` contract Hanami's `Response#render` expects, a layout,
+    # and everything in {Contextual}: per-slice configuration and the request's view context.
+    #
+    # A component is not called by Hanami and wants no layout, so it includes {Contextual} on its
+    # own. {Component} does that already.
     #
     # @example
     #   module MyApp
@@ -22,70 +25,21 @@ module Phlex
       #
       # @api private
       # @since 0.2.0
-      KEYWORD_TYPES = %i[key keyreq].freeze
+      KEYWORD_TYPES = %i[key keyreq].freeze #: Array[Symbol]
 
       # Distinguishes "no layout was configured" from "a layout of `nil` was configured", which is
       # how a view opts out.
       #
       # @api private
       # @since 0.2.0
-      UNSET = ::Object.new.freeze
+      UNSET = ::Object.new.freeze #: Object
 
       # @api private
       # @since 0.2.0
+      #: (singleton(::Phlex::SGML)) -> void
       def self.included(view_class)
-        view_class.extend(::Hanami::SliceConfigurable)
+        view_class.include(Contextual)
         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.
-        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.
-        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
@@ -111,6 +65,7 @@ module Phlex
         #
         # @api public
         # @since 0.2.0
+        #: (?context: (::Hanami::View::Context | Context)?, **untyped) -> String
         def call(context: nil, **input)
           phlex_context = { CONTEXT_KEY => context }
           body = new(**accepted_input(input)).call(context: phlex_context)
@@ -121,17 +76,12 @@ module Phlex
           layout_class.new.call(context: phlex_context) { |layout| layout.raw(layout.safe(body)) }
         end
 
-        # @api private
-        # @since 0.2.0
-        def configure_for_slice(slice)
-          extend SliceConfigured.new(slice)
-        end
-
         # The layout configured on this class, or inherited from a superclass. {UNSET} when none has
         # been configured anywhere in the chain.
         #
         # @api private
         # @since 0.2.0
+        #: () -> (singleton(::Phlex::SGML) | Object | nil)
         def configured_layout
           return @layout if defined?(@layout)
           return superclass.configured_layout if superclass.respond_to?(:configured_layout)
@@ -165,6 +115,7 @@ module Phlex
         #
         # @api public
         # @since 0.2.0
+        #: (?singleton(::Phlex::SGML)?) -> singleton(::Phlex::SGML)?
         def layout(layout_class = UNSET)
           unless UNSET.equal?(layout_class)
             @layout = layout_class
@@ -175,22 +126,13 @@ module Phlex
           UNSET.equal?(configured) ? default_layout : configured
         end
 
-        # The slice this view belongs to, or nil when it is defined outside a slice namespace.
-        #
-        # @return [Hanami::Slice, nil]
-        #
-        # @api public
-        # @since 0.2.0
-        def slice
-          nil
-        end
-
         private
 
         # Keeps only the keywords `initialize` declares.
         #
         # A view whose initializer takes `**` opts out and receives everything, request params
         # included.
+        #: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
         def accepted_input(input)
           parameters = instance_method(:initialize).parameters
           return input if parameters.any? { |type, _| type == :keyrest }
@@ -200,6 +142,7 @@ module Phlex
 
         # The slice's conventional layout: `Views::Layout` in the slice's namespace, if it defines
         # one. Resolved on each call rather than memoized, so code reloading is not defeated.
+        #: () -> singleton(::Phlex::SGML)?
         def default_layout
           return nil unless slice
           return nil unless slice.namespace.const_defined?(:Views, false)
@@ -208,172 +151,6 @@ module Phlex
           views.const_get(:Layout, false) if views.const_defined?(:Layout, false)
         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
-      def asset_url(source)
-        assets[source].url
-      end
-
-      # The slice's assets.
-      #
-      # @api public
-      # @since 0.2.0
-      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
-      def content_for(...)
-        hanami_context.content_for(...)
-      end
-
-      # The current request's CSRF token.
-      #
-      # @return [String]
-      #
-      # @api public
-      # @since 0.2.0
-      def csrf_token
-        hanami_context.csrf_token
-      end
-
-      # The flash hash for the current request.
-      #
-      # @api public
-      # @since 0.2.0
-      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
-      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
-      def hanami_context?
-        !context[CONTEXT_KEY].nil?
-      end
-
-      # The slice's i18n backend.
-      #
-      # @api public
-      # @since 0.2.0
-      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
-      def path(...)
-        routes.path(...)
-      end
-
-      # The current request.
-      #
-      # @return [Hanami::Action::Request]
-      #
-      # @api public
-      # @since 0.2.0
-      def request
-        hanami_context.request
-      end
-
-      # Whether the view is being rendered from within a request.
-      #
-      # @return [Boolean]
-      #
-      # @api public
-      # @since 0.2.0
-      def request?
-        hanami_context? && hanami_context.request?
-      end
-
-      # The app's routes helper.
-      #
-      # @return [Hanami::Slice::RoutesHelper]
-      #
-      # @api public
-      # @since 0.2.0
-      def routes
-        hanami_context.routes
-      end
-
-      # The session for the current request.
-      #
-      # @api public
-      # @since 0.2.0
-      def session
-        hanami_context.session
-      end
-
-      # The slice this view belongs to.
-      #
-      # @return [Hanami::Slice, nil]
-      #
-      # @api public
-      # @since 0.2.0
-      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
-      def url(...)
-        routes.url(...).to_s
-      end
-
-      private
-
-      # Hanami's helper modules reach for the view context under this name.
-      def _context
-        hanami_context
-      end
     end
   end
 end

data/lib/phlex/hanami/rspec.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "testing"
+
+# Wires {Phlex::Hanami::Testing::ViewHelpers} into RSpec. Require it from `spec/spec_helper.rb`, or
+# from a file under `spec/support`, which the spec helper hanami-rspec generates already loads:
+#
+#     require "phlex/hanami/rspec"
+#
+# The helpers go into every example group tagged `type: :view`. Tag component specs the same way; a
+# component is a view as far as this is concerned.
+RSpec.configure do |config|
+  config.include Phlex::Hanami::Testing::ViewHelpers, type: :view
+end

data/lib/phlex/hanami/slice_configured.rb

@@ -17,10 +17,11 @@ module Phlex
       #
       # @api private
       # @since 0.2.0
-      attr_reader :slice
+      attr_reader :slice #: singleton(::Hanami::Slice)
 
       # @api private
       # @since 0.2.0
+      #: (singleton(::Hanami::Slice)) -> void
       def initialize(slice)
         super()
         @slice = slice
@@ -28,18 +29,21 @@ module Phlex
 
       # @api private
       # @since 0.2.0
+      #: (singleton(::Phlex::SGML) | singleton(::Hanami::Mailer)) -> void
       def extended(_klass)
         define_slice
       end
 
       # @api private
       # @since 0.2.0
+      #: () -> String
       def inspect
         "#<#{self.class.name}[#{slice.name}]>"
       end
 
       private
 
+      #: () -> void
       def define_slice
         slice = @slice
 

data/lib/phlex/hanami/slice_configured_context.rb

@@ -16,10 +16,11 @@ module Phlex
       #
       # @api private
       # @since 0.2.0
-      attr_reader :slice
+      attr_reader :slice #: singleton(::Hanami::Slice)
 
       # @api private
       # @since 0.2.0
+      #: (singleton(::Hanami::Slice)) -> void
       def initialize(slice)
         super()
         @slice = slice
@@ -27,12 +28,14 @@ module Phlex
 
       # @api private
       # @since 0.2.0
+      #: (singleton(Context)) -> void
       def extended(_context_class)
         define_new
       end
 
       # @api private
       # @since 0.2.0
+      #: () -> String
       def inspect
         "#<#{self.class.name}[#{slice.name}]>"
       end
@@ -40,6 +43,7 @@ module Phlex
       private
 
       # Defines a `.new` that resolves the slice's components and passes them to `#initialize`.
+      #: () -> void
       def define_new
         dependencies = method(:dependencies)
 
@@ -50,18 +54,22 @@ module Phlex
 
       # The slice components a context is injected with, resolved fresh for each context so that
       # a container which does not memoize still hands out working objects.
+      #: () -> Hash[Symbol, untyped]
       def dependencies
         { assets: resolve_assets, i18n: resolve_i18n, inflector: slice.inflector, routes: resolve_routes }
       end
 
+      #: () -> ::Hanami::Assets?
       def resolve_assets
         slice["assets"] if slice.key?("assets")
       end
 
+      #: () -> ::Hanami::Providers::I18n::Backend?
       def resolve_i18n
         slice["i18n"] if slice.key?("i18n")
       end
 
+      #: () -> ::Hanami::Slice::RoutesHelper?
       def resolve_routes
         slice["routes"] if slice.key?("routes")
       end