hanami-view 2.0.0.alpha8 → 2.1.0.beta1

data/lib/hanami/view/helpers/tag_helper.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+# Based on ActionView::Helpers::TagHelper, also released under the MIT licence.
+#
+# Copyright (c) David Heinemeier Hansson
+
+module Hanami
+  class View
+    module Helpers
+      # Helper methods for generating HTML tags.
+      #
+      # When using full Hanami apps, these helpers will be automatically available in your view
+      # templates, part classes and scope classes.
+      #
+      # When using hanami-view standalone, include this module directly in your base part and scope
+      # classes, or in specific classes as required.
+      #
+      # @example Standalone usage
+      #   class BasePart < Hanami::View::Part
+      #     include Hanami::View::Helpers::TagHelper
+      #   end
+      #
+      #   class BaseScope < Hanami::View::Scope
+      #     include Hanami::View::Helpers::TagHelper
+      #   end
+      #
+      #   class BaseView < Hanami::View
+      #     config.part_class = BasePart
+      #     config.scope_class = BaseScope
+      #   end
+      #
+      # @api public
+      # @since 2.0.0
+      module TagHelper
+        module_function
+
+        # Returns a tag builder for building HTML tag strings.
+        #
+        # @example General usage
+        #   tag.div # => <div></div>
+        #   tag.img # => <img>
+        #
+        #   tag.div("hello")        # => <div>hello</div>
+        #   tag.div { "hello" }     # => <div>hello</div>
+        #   tag.div(tag.p("hello")) # => <div><p>hello</p></div>
+        #
+        #   tag.div(class: ["a", "b"])              # => <div class="a b"></div>
+        #   tag.div(class: {"a": true, "b": false}) # => <div class="a"></div>
+        #
+        #   tag.div(id: "el", data: {x: "y"}) # => <div id="el" data-x="y"></div>
+        #   tag.div(id: "el", aria: {x: "y"}) # => <div id="el" aria-x="y"></div>
+        #
+        #   tag.custom_tag("hello") # => <custom-tag>hello</custom-tag>
+        #
+        # @example Escaping
+        #   tag.p("<script>alert()</script>")         # => <p>&lt;script&gt;alert()&lt;/script&gt;</p>
+        #   tag.p(class: "<script>alert()</script>")  # => <p class="&lt;script&gt;alert()&lt;/script&gt;"></p>
+        #   tag.p("<em>safe content</em>".html_safe)  # => <p><em>safe content</em></p>
+        #
+        # @example Within templates
+        #   <%= tag.div(id: "el") do %>
+        #     <p>Template content can be mixed in.</p>
+        #     <%= tag.p("Also nested tag builders.") %>
+        #   <% end %>
+        #
+        # @api public
+        # @since 2.0.0
+        def tag
+          tag_builder
+        end
+
+        # Returns an anchor tag for the given contents and URL.
+        #
+        # The tag's contents are automatically escaped (unless marked as HTML safe).
+        #
+        # Uses the {#tag} builder to prepare the tag, so all tag builder options are also used.
+        #
+        # @overload link_to(content, url, **attributes)
+        #   Returns a tag using a given string as the contents.
+        #
+        #   @param content [String] content used in the a tag
+        #   @param url [String] URL to be used in the `href` attribute
+        #   @param attributes [Hash] HTML attributes to include in the tag
+        #
+        # @overload link_to(url, **attributes, &block)
+        #   Returns a tag using the given block's return value as the contents.
+        #
+        #   @param url [String] URL to be used in the `href` attribute
+        #   @param attributes [Hash] HTML attributes to include in the tag
+        #   @param block [Proc] block that returns the contents of the tag
+        #
+        # @return [String] HTML markup for the anchor tag
+        #
+        # @example
+        #   link_to("Home", "/")
+        #   # => <a href="/">Home</a>
+        #
+        #   link_to("/") { "Home" }
+        #   # => <a href="/">Home</a>
+        #
+        #   link_to("Home", "/", class: "button") %>
+        #   # => <a href="/" class="button">Home</a>
+        #
+        # @example Escaping
+        #   link_to("<script>alert('xss')</script>", "/")
+        #   # => <a href="/">&lt;script&gt;alert(&#39;xss&#39;)&lt;/script&gt;</a>
+        #
+        #   link_to("/") { "<script>alert('xss')</script>" }
+        #   # => <a href="/">&lt;script&gt;alert(&#39;xss&#39;)&lt;/script&gt;</a>
+        #
+        # @see #tag
+        #
+        # @api public
+        # @since 2.0.0
+        def link_to(content, url = nil, **attributes, &block)
+          if block
+            raise ArgumentError if url && content
+
+            url = content
+            content = nil
+          end
+
+          attributes[:href] = url or raise ArgumentError
+
+          tag.a(content, **attributes, &block)
+        end
+
+        # Returns a string of space-separated tokens from a range of given arguments.
+        #
+        # This is intended for building an HTML tag attribute value, such as a list of class names.
+        #
+        # @return [String]
+        #
+        # @example
+        #   token_list("foo", "bar")
+        #   # => "foo bar"
+        #
+        #   token_list("foo", "foo bar")
+        #   # => "foo bar"
+        #
+        #   token_list({ foo: true, bar: false })
+        #   # => "foo"
+        #
+        #   token_list(nil, false, 123, "", "foo", { bar: true })
+        #   # => "123 foo bar"
+        #
+        # @api public
+        # @since 2.0.0
+        def token_list(*args)
+          tokens = build_tag_values(*args).flat_map { |value|
+            safe = value.html_safe?
+            value.split(/\s+/).map { |s| safe ? s.html_safe : s }
+          }
+
+          EscapeHelper.escape_join(tokens, " ")
+        end
+
+        # @see #token_list
+        #
+        # @api public
+        # @since 2.0.0
+        def class_names(...)
+          token_list(...)
+        end
+
+        # @api private
+        # @since 2.0.0
+        def build_tag_values(*args)
+          tag_values = []
+
+          args.each do |tag_value|
+            case tag_value
+            when Hash
+              tag_value.each do |key, val|
+                tag_values << key.to_s if val && !key.to_s.empty?
+              end
+            when Array
+              tag_values.concat build_tag_values(*tag_value)
+            else
+              tag_values << tag_value.to_s unless tag_value.to_s.empty?
+            end
+          end
+
+          tag_values
+        end
+
+        # @api private
+        # @since 2.0.0
+        def tag_builder
+          @tag_builder ||= begin
+            TagBuilder.new(inflector: tag_builder_inflector)
+          end
+        end
+
+        # @api private
+        # @since 2.0.0
+        def tag_builder_inflector
+          if respond_to?(:_context)
+            return _context.inflector
+          end
+
+          # TODO: When hanami-view moves to Zeitwerk (and the only external require is for
+          # "dry/view"), remove this.
+          require "dry/inflector"
+          Dry::Inflector.new
+        end
+      end
+    end
+  end
+end

data/lib/hanami/view/html.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Hanami
+  class View
+    module HTML
+      # A string that has been marked as "HTML safe", ensuring that it is not automatically escaped
+      # when used in HTML view templates.
+      #
+      # A SafeString is frozen when initialized to ensure it cannot be mutated after being marked as
+      # safe, which could be an avenue for injection of unsafe content.
+      #
+      # @see String#html_safe
+      #
+      # @api public
+      # @since 2.0.0
+      class SafeString < String
+        # @api public
+        # @since 2.0.0
+        def initialize(string)
+          super(string)
+          freeze
+        end
+
+        # @api private
+        private def initialize_copy(other)
+          super
+          freeze
+        end
+
+        # @return [true]
+        #
+        # @api public
+        # @since 2.0.0
+        def html_safe?
+          true
+        end
+
+        # @return [self]
+        #
+        # @api public
+        # @since 2.0.0
+        def html_safe
+          self
+        end
+
+        # @return [self]
+        #
+        # @api public
+        # @since 2.0.0
+        def to_s
+          self
+        end
+      end
+
+      # @api private
+      # @since 2.0.0
+      module StringExtensions
+        # Returns the string as a {Hanami::View::HTML::SafeString}, ensuring the string is not
+        # automatically escaped when used in HTML view templates.
+        #
+        # @return [Hanami::View::HTML::SafeString]
+        #
+        # @api public
+        # @since 2.0.0
+        def html_safe
+          Hanami::View::HTML::SafeString.new(self)
+        end
+      end
+    end
+  end
+end
+
+class String
+  # Prepend our `#html_safe` method so that it takes precedence over Active Support's. When both
+  # methods are loaded, the more likely scenario is that the user will want Hanami's, since in the
+  # context of a Hanami app, Active Support is more likely to be loaded incidentally, as a
+  # transitive dependency of another gem.
+  #
+  # Having our `#html_safe` available via this module also means that a user can also choose to
+  # _undefine_ this method within the module if they'd rather use Active Support's.
+  prepend Hanami::View::HTML::StringExtensions
+end
+
+class Object
+  # @return [false]
+  #
+  # @api public
+  # @since 2.0.0
+  def html_safe?
+    false
+  end
+end
+
+class Numeric
+  # @return [true]
+  #
+  # @api public
+  # @since 2.0.0
+  def html_safe?
+    true
+  end
+end
+
+

data/lib/hanami/view/html_safe_string_buffer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "temple"
+
+module Hanami
+  class View
+    # Specialized Temple buffer class that marks block-captured strings as HTML safe.
+    #
+    # This is important for any scope or part methods that receive a string from a yielded block
+    # and then determine whether to escape that string based on its `.html_safe?` value.
+    #
+    # In this case, since blocks captured templates _intentionally_ contain HTML (this is the
+    # purpose of the template after all), it makes sense to mark the entire captured block string as
+    # HTML safe.
+    #
+    # This is compatible with escaping of values interpolated into the template, since those will
+    # have already been automatically escaped by the template engine when they are evaluated, before
+    # the overall block is captured.
+    #
+    # This filter is included in all three of our supported HTML template engines (ERB, Haml and
+    # Slim) to provide consistent behavior across all.
+    #
+    # @see Hanami::View::ERB::Engine
+    # @see Hanami::View::HamlAdapter::Template
+    # @see Hanami::View::SlimAdapter::Template
+    #
+    # @api private
+    # @since 2.0.0
+    class HTMLSafeStringBuffer < Temple::Generators::StringBuffer
+      # Replace `Temple::Generator::ArrayBuffer#call` (which is used via the superclass of
+      # `StringBuffer`) with the standard implementation from the base `Temple::Generator`.
+      #
+      # This avoids certain specialisations in `ArrayBuffer#call` that prevent `#return_buffer` from
+      # being called. For our needs, `#return_buffer` must be called at all times in order to ensure
+      # the captured string is consistently marked as `.html_safe`.
+      def call(exp)
+        [preamble, compile(exp), postamble].flatten.compact.join('; ')
+      end
+
+      # Marks the string returned from the captured buffer as HTML safe.
+      def return_buffer
+        "#{buffer}.html_safe"
+      end
+    end
+  end
+end

data/lib/hanami/view/part.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 require "dry/core/equalizer"
-require_relative "decorated_attributes"
-require_relative "render_environment_missing"
 
 module Hanami
   class View
@@ -25,7 +23,7 @@ module Hanami
         value
       ].freeze
 
-      include Dry::Equalizer(:_name, :_value, :_render_env)
+      include Dry::Equalizer(:_name, :_value, :_rendering)
       include DecoratedAttributes
 
       # The part's name. This comes from the exposure supplying the value.
@@ -48,12 +46,12 @@ module Hanami
       # @api public
       attr_reader :_value
 
-      # The current render environment
+      # The current rendering
       #
-      # @return [RenderEnvironment] render environment
+      # @return [Rendering]
       #
       # @api private
-      attr_reader :_render_env
+      attr_reader :_rendering
 
       # Determins a part name (when initialized without one). Intended for use
       # only while unit testing Parts.
@@ -67,17 +65,17 @@ module Hanami
       #
       # @param name [Symbol] part name
       # @param value [Object] the value to decorate
-      # @param render_env [RenderEnvironment] render environment
+      # @param rendering [Rendering] the current rendering
       #
       # @api public
       def initialize(
-        render_env: RenderEnvironmentMissing.new,
-        name: self.class.part_name(render_env.inflector),
+        rendering: RenderingMissing.new,
+        name: self.class.part_name(rendering.inflector),
         value:
       )
         @_name = name
         @_value = value
-        @_render_env = render_env
+        @_rendering = rendering
       end
 
       # The template format for the current render environment.
@@ -92,7 +90,7 @@ module Hanami
       #
       # @api public
       def _format
-        _render_env.format
+        _rendering.format
       end
 
       # The context object for the current render environment
@@ -107,7 +105,7 @@ module Hanami
       #
       # @api public
       def _context
-        _render_env.context
+        _rendering.context
       end
 
       # Renders a new partial with the part included in its locals.
@@ -128,7 +126,7 @@ module Hanami
       # @api public
       # rubocop:disable Naming/UncommunicativeMethodParamName
       def _render(partial_name, as: _name, **locals, &block)
-        _render_env.partial(partial_name, _render_env.scope({as => self}.merge(locals)), &block)
+        _rendering.partial(partial_name, _rendering.scope({as => self}.merge(locals)), &block)
       end
       # rubocop:enable Naming/UncommunicativeMethodParamName
 
@@ -148,7 +146,7 @@ module Hanami
       #
       # @api public
       def _scope(scope_name = nil, **locals)
-        _render_env.scope(scope_name, {_name => self}.merge(locals))
+        _rendering.scope(scope_name, {_name => self}.merge(locals))
       end
 
       # Returns a string representation of the value
@@ -180,7 +178,7 @@ module Hanami
         klass.new(
           name: name,
           value: value,
-          render_env: _render_env,
+          rendering: _rendering,
           **options
         )
       end

data/lib/hanami/view/part_builder.rb

@@ -1,139 +1,99 @@
 # frozen_string_literal: true
 
-require "dry/core/cache"
-require "dry/core/equalizer"
-require_relative "part"
-
 module Hanami
   class View
     # Decorates exposure values with matching parts
     #
     # @api private
     class PartBuilder
-      extend Dry::Core::Cache
-      include Dry::Equalizer(:namespace)
-
-      attr_reader :namespace
-      attr_reader :render_env
-
-      # Returns a new instance of PartBuilder
-      #
-      # @api private
-      def initialize(namespace: nil, render_env: nil)
-        @namespace = namespace
-        @render_env = render_env
-      end
-
-      # @api private
-      def for_render_env(render_env)
-        return self if render_env == self.render_env
-
-        self.class.new(namespace: namespace, render_env: render_env)
-      end
-
-      # Decorates an exposure value
-      #
-      # @param name [Symbol] exposure name
-      # @param value [Object] exposure value
-      # @param options [Hash] exposure options
-      #
-      # @return [Hanami::View::Part] decorated value
-      #
-      # @api private
-      def call(name, value, **options)
-        builder = value.respond_to?(:to_ary) ? :build_collection_part : :build_part
-
-        send(builder, name, value, **options)
-      end
-
-      private
-
-      def build_part(name, value, **options)
-        klass = part_class(name: name, **options)
+      class << self
+        # Decorates an exposure value
+        #
+        # @param name [Symbol] exposure name
+        # @param value [Object] exposure value
+        # @param as [Symbol, nil] alternative name to use for part class resolution
+        #
+        # @return [Hanami::View::Part] decorated value
+        #
+        # @api private
+        def call(name, value, as: nil, rendering:)
+          builder = value.respond_to?(:to_ary) ? :build_collection_part : :build_part
+
+          send(builder, name: name, value: value, as: as, rendering: rendering)
+        end
 
-        klass.new(
-          name: name,
-          value: value,
-          render_env: render_env
-        )
-      end
+        private
 
-      def build_collection_part(name, value, **options)
-        collection_as = collection_options(name: name, **options)[:as]
-        item_name, item_as = collection_item_options(name: name, **options).values_at(:name, :as)
+        def build_part(name:, value:, as:, rendering:)
+          klass = part_class(name: name, as: as, rendering: rendering)
 
-        arr = value.to_ary.map { |obj|
-          build_part(item_name, obj, **options.merge(as: item_as))
-        }
+          klass.new(name: name, value: value, rendering: rendering)
+        end
 
-        build_part(name, arr, **options.merge(as: collection_as))
-      end
+        def build_collection_part(name:, value:, as: nil, rendering:)
+          item_name, item_as = collection_item_name_as(name, as, inflector: rendering.inflector)
+          item_part_class = part_class(name: item_name, as: item_as, rendering: rendering)
 
-      # rubocop:disable Lint/UnusedMethodArgument
-      def collection_options(name:, **options)
-        collection_as = options[:as].is_a?(Array) ? options[:as].first : nil
+          arr = value.to_ary.map { |item|
+            item_part_class.new(name: item_name, value: item, rendering: rendering)
+          }
 
-        options.merge(as: collection_as)
-      end
-      # rubocop:enable Lint/UnusedMethodArgument
+          collection_as = as.is_a?(Array) ? as.first : nil
+          build_part(name: name, value: arr, as: collection_as, rendering: rendering)
+        end
 
-      def collection_item_options(name:, **options)
-        singular_name = inflector.singularize(name).to_sym
-        singular_as =
-          if options[:as].is_a?(Array)
-            options[:as].last if options[:as].length > 1
-          else
-            options[:as]
+        def collection_item_name_as(name, as, inflector:)
+          singular_name = inflector.singularize(name).to_sym
+          singular_as =
+            if as.is_a?(Array)
+              as.last if as.length > 1
+            else
+              as
+            end
+
+          if singular_as && !singular_as.is_a?(Class)
+            singular_as = inflector.singularize(singular_as.to_s)
           end
 
-        if singular_as && !singular_as.is_a?(Class)
-          singular_as = inflector.singularize(singular_as.to_s)
+          [singular_name, singular_as]
         end
 
-        options.merge(
-          name: singular_name,
-          as: singular_as
-        )
-      end
-
-      def part_class(name:, fallback_class: Part, **options)
-        name = options[:as] || name
+        def part_class(name:, as:, rendering:)
+          name = as || name
 
-        if name.is_a?(Class)
-          name
-        else
-          fetch_or_store(namespace, name, fallback_class) do
-            resolve_part_class(name: name, fallback_class: fallback_class)
+          if name.is_a?(Class)
+            name
+          else
+            View.cache.fetch_or_store(:part_class, name, rendering.config) do
+              resolve_part_class(name: name, rendering: rendering)
+            end
           end
         end
-      end
 
-      # rubocop:disable Metrics/PerceivedComplexity
-      def resolve_part_class(name:, fallback_class:)
-        return fallback_class unless namespace
+        # rubocop:disable Metrics/PerceivedComplexity
+        def resolve_part_class(name:, rendering:)
+          namespace = rendering.config.part_namespace
+          return rendering.config.part_class unless namespace
 
-        name = inflector.camelize(name.to_s)
+          name = rendering.inflector.camelize(name.to_s)
 
-        # Give autoloaders a chance to act
-        begin
-          klass = namespace.const_get(name)
-        rescue NameError # rubocop:disable Lint/HandleExceptions
-        end
+          # Give autoloaders a chance to act
+          begin
+            klass = namespace.const_get(name)
+          rescue NameError # rubocop:disable Lint/HandleExceptions
+          end
 
-        if !klass && namespace.const_defined?(name, false)
-          klass = namespace.const_get(name)
-        end
+          if !klass && namespace.const_defined?(name, false)
+            klass = namespace.const_get(name)
+          end
 
-        if klass && klass < Part
-          klass
-        else
-          fallback_class
+          if klass && klass < Part
+            klass
+          else
+            rendering.config.part_class
+          end
         end
-      end
-      # rubocop:enable Metrics/PerceivedComplexity
-
-      def inflector
-        render_env.inflector
+        # rubocop:enable Metrics/PerceivedComplexity
       end
     end
   end