hanami-view 2.0.0.alpha8 → 2.1.0.beta1

data/lib/hanami/view/exposures.rb

@@ -2,7 +2,6 @@
 
 require "tsort"
 require "dry/core/equalizer"
-require_relative "exposure"
 
 module Hanami
   class View
@@ -46,18 +45,28 @@ module Hanami
       end
 
       def call(input)
-        # rubocop:disable Style/MultilineBlockChain
-        tsort.each_with_object({}) { |name, memo|
-          next unless (exposure = self[name])
-
-          value = exposure.(input, memo)
-          value = yield(value, exposure) if block_given?
-
-          memo[name] = value
-        }.each_with_object({}) { |(name, value), memo|
-          memo[name] = value unless self[name].private?
-        }
-        # rubocop:enable Style/MultilineBlockChain
+        # Avoid performance cost of tsorting when we don't need it
+        names =
+          if exposures.values.any?(&:dependencies?) # TODO: this sholud be cachable at time of `#add`
+            tsort
+          else
+            exposures.keys
+          end
+
+        names
+          .each_with_object({}) { |name, memo|
+            next unless (exposure = self[name])
+
+            value = exposure.(input, memo)
+            value = yield(value, exposure) if block_given?
+
+            memo[name] = value
+          }
+          .tap { |hsh|
+            names.each do |key|
+              hsh.delete(key) if self[key].private?
+            end
+          }
       end
 
       private

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

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require "temple"
+require "uri"
+
+module Hanami
+  class View
+    module Helpers
+      # Helper methods for escaping content for safely including in HTML.
+      #
+      # 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::EscapeHelper
+      #   end
+      #
+      #   class BaseScope < Hanami::View::Scope
+      #     include Hanami::View::Helpers::EscapeHelper
+      #   end
+      #
+      #   class BaseView < Hanami::View
+      #     config.part_class = BasePart
+      #     config.scope_class = BaseScope
+      #   end
+      #
+      # @api public
+      # @since 2.0.0
+      module EscapeHelper
+        module_function
+
+        # Returns an escaped string that is safe to include in HTML.
+        #
+        # Use this helper when including any untrusted user input in your view content.
+        #
+        # If the given string is already marked as HTML safe, then it will be returned without
+        # escaping.
+        #
+        # Marks the escaped string marked as HTML safe, ensuring it will not be escaped again.
+        #
+        # @param input [String] the input string
+        # @return [Hanami::View::HTML::SafeString] the escaped string
+        #
+        # @example
+        #   escape_html("Safe content")
+        #   # => "Safe content"
+        #
+        #   escape_html("<script>alert('xss')</script>")
+        #   # => "&lt;script&gt;alert(&#39;xss&#39;)&lt;/script&gt;"
+        #
+        #   escape_html(raw("<p>Not escaped</p>"))
+        #   # => "<p>Not escaped</p>"
+        #
+        # @api public
+        # @since 2.0.0
+        def escape_html(input)
+          Temple::Utils.escape_html_safe(input)
+        end
+
+        # @api public
+        # @since 2.0.0
+        alias_method :h, :escape_html
+
+        # Returns an escaped string from joining the elements in a given array.
+        #
+        # Behaves similarly to `Array#join`. The given array is flattened, and all items, including
+        # the supplied separator, are HTML escaped unless they are already HTML safe.
+        #
+        # Marks the returned string as HTML safe, ensuring it will not be escaped again.
+        #
+        # @param array [Array<#to_s>] the array
+        # @param separator[String] the separator for the joined string
+        # @return [Hanami::View::HTML::SafeString] the escaped string
+        #
+        # @example
+        #   safe_join([raw("<p>foo</p>"), "<p>bar</p>"], "<br>")
+        #   # => "<p>foo</p>&lt;br&gt;&lt;p&gt;bar&lt;/p&gt;"
+        #
+        #   safe_join([raw("<p>foo</p>"), raw("<p>bar</p>")], raw("<br>"))
+        #   # => "<p>foo</p><br><p>bar</p>"
+        #
+        # @see #escape_html
+        #
+        # @api public
+        # @since 2.0.0
+        def escape_join(array, separator = $,)
+          separator = escape_html(separator)
+
+          array.flatten.map! { |i| escape_html(i) }.join(separator).html_safe
+        end
+
+        # Returns a the given URL string if it has one of the permitted URL schemes. For URLs with
+        # non-permitted schemes, returns an empty string.
+        #
+        # Use this method when including URLs from untrusted user input in your view content.
+        #
+        # The default permitted schemes are:
+        # - `http`
+        # - `https`
+        # - `mailto`
+        #
+        # @param input [String] the URL string
+        # @param permitted_schemes [Array<string>] an optional array of permitted schemes
+        #
+        # @return [String] the permitted URL, or empty string
+        #
+        # @example
+        #   sanitize_url("https://hanamirb.org")    # => "http://hanamirb.org"
+        #   sanitize_url("javascript:alert('xss')") # => ""
+        #
+        #   sanitize_url("gemini://gemini.circumlunar.space/", %w[http https gemini])
+        #   # => "gemini://gemini.circumlunar.space/"
+        #
+        # @api public
+        # @since 2.0.0
+        def sanitize_url(input, permitted_schemes = PERMITTED_URL_SCHEMES)
+          return input if input.html_safe?
+
+          URI::DEFAULT_PARSER.extract(
+            URI.decode_www_form_component(input.to_s),
+            permitted_schemes
+          ).first.to_s.html_safe
+        end
+
+        # @api private
+        # @since 2.0.0
+        PERMITTED_URL_SCHEMES = %w[http https mailto].freeze
+        private_constant :PERMITTED_URL_SCHEMES
+
+        # Returns an escaped name from the given string, intended for use as an XML tag or attribute
+        # name.
+        #
+        # Replaces non-safe characters with an underscore.
+        #
+        # Follows the requirements of the [XML specification](https://www.w3.org/TR/REC-xml/#NT-Name).
+        #
+        # @example
+        #   escape_xml_name("1 < 2 & 3") # => "1___2___3"
+        #
+        # @api public
+        # @since 2.0.0
+        def escape_xml_name(name)
+          name = name.to_s
+          return "" if name.match?(BLANK_STRING_REGEXP)
+          return name if name.match?(SAFE_XML_TAG_NAME_REGEXP)
+
+          starting_char = name[0]
+          starting_char.gsub!(INVALID_TAG_NAME_START_REGEXP, TAG_NAME_REPLACEMENT_CHAR)
+
+          return starting_char if name.size == 1
+
+          following_chars = name[1..-1]
+          following_chars.gsub!(INVALID_TAG_NAME_FOLLOWING_REGEXP, TAG_NAME_REPLACEMENT_CHAR)
+
+          starting_char << following_chars
+        end
+
+        # @api private
+        # @since 2.0.0
+        BLANK_STRING_REGEXP = /\A\s*\z/
+
+        # Following XML requirements: https://www.w3.org/TR/REC-xml/#NT-Name
+        # @api private
+        # @since 2.0.0
+        TAG_NAME_START_CODEPOINTS = \
+          "@:A-Z_a-z\u{C0}-\u{D6}\u{D8}-\u{F6}\u{F8}-\u{2FF}\u{370}-\u{37D}\u{37F}-\u{1FFF}" \
+          "\u{200C}-\u{200D}\u{2070}-\u{218F}\u{2C00}-\u{2FEF}\u{3001}-\u{D7FF}\u{F900}-\u{FDCF}" \
+          "\u{FDF0}-\u{FFFD}\u{10000}-\u{EFFFF}"
+        private_constant :TAG_NAME_START_CODEPOINTS
+
+        # @api private
+        # @since 2.0.0
+        INVALID_TAG_NAME_START_REGEXP = /[^#{TAG_NAME_START_CODEPOINTS}]/
+        private_constant :INVALID_TAG_NAME_START_REGEXP
+
+        # @api private
+        # @since 2.0.0
+        TAG_NAME_FOLLOWING_CODEPOINTS = "#{TAG_NAME_START_CODEPOINTS}\\-.0-9\u{B7}\u{0300}-\u{036F}\u{203F}-\u{2040}"
+        private_constant :TAG_NAME_FOLLOWING_CODEPOINTS
+
+        # @api private
+        # @since 2.0.0
+        INVALID_TAG_NAME_FOLLOWING_REGEXP = /[^#{TAG_NAME_FOLLOWING_CODEPOINTS}]/
+        private_constant :INVALID_TAG_NAME_FOLLOWING_REGEXP
+
+        # @api private
+        # @since 2.0.0
+        SAFE_XML_TAG_NAME_REGEXP = /\A[#{TAG_NAME_START_CODEPOINTS}][#{TAG_NAME_FOLLOWING_CODEPOINTS}]*\z/
+        private_constant :INVALID_TAG_NAME_FOLLOWING_REGEXP
+
+        # @api private
+        # @since 2.0.0
+        TAG_NAME_REPLACEMENT_CHAR = "_"
+        private_constant :TAG_NAME_REPLACEMENT_CHAR
+
+        # Returns the given string marked as HTML safe, meaning it will not be escaped when included
+        # in your view's HTML.
+        #
+        # This is NOT recommended if the string is coming from untrusted user input. Use at your own
+        # peril.
+        #
+        # @param input [String] the input
+        # @return [Hanami::View::HTML::SafeString] the string marked as HTML safe
+        #
+        # @example
+        #   raw(user.name) # => "Little Bobby <alert>Tables</alert>"
+        #   raw(user.name).html_safe? # => true
+        #
+        # @api public
+        # @since 2.0.0
+        def raw(input)
+          input.to_s.html_safe
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Hanami
+  class View
+    module Helpers
+      # Helper methods for formatting numbers as text.
+      #
+      # 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::NumberFormattingHelper
+      #   end
+      #
+      #   class BaseScope < Hanami::View::Scope
+      #     include Hanami::View::Helpers::NumberFormattingHelper
+      #   end
+      #
+      #   class BaseView < Hanami::View
+      #     config.part_class = BasePart
+      #     config.scope_class = BaseScope
+      #   end
+      #
+      # @api public
+      # @since 2.0.0
+      module NumberFormattingHelper
+        module_function
+
+        # Default delimiter
+        #
+        # @return [String] default delimiter
+        #
+        # @since 2.0.0
+        # @api private
+        DEFAULT_DELIMITER = ","
+        private_constant :DEFAULT_DELIMITER
+
+        # Default separator
+        #
+        # @return [String] default separator
+        #
+        # @since 2.0.0
+        # @api private
+        DEFAULT_SEPARATOR = "."
+        private_constant :DEFAULT_SEPARATOR
+
+        # Default precision
+        #
+        # @return [Integer] default rounding precision
+        #
+        # @since 2.0.0
+        # @api private
+        DEFAULT_PRECISION = 2
+        private_constant :DEFAULT_PRECISION
+
+        # Returns a formatted string for the given number.
+        #
+        # Accepts a number (`Numeric`) or a string representation of a number.
+        #
+        # If an integer is given, applies no precision in the returned string. For all other kinds
+        # (`Float`, `BigDecimal`, etc.), formats the number as a float.
+        #
+        # Raises an `ArgumentError` if the argument cannot be coerced into a number for formatting.
+        #
+        # @param number [Numeric, String] the number to be formatted
+        # @param delimiter [String] hundred delimiter
+        # @param separator [String] fractional part separator
+        # @param precision [String] rounding precision
+        #
+        # @return [String] formatted number
+        #
+        # @raise [ArgumentError] if the number can't be formatted
+        #
+        # @example
+        #   format_number(1_000_000) # => "1,000,000"
+        #   format_number(Math::PI) # => "3.14"
+        #   format_number(Math::PI, precision: 4) # => "3.1416"
+        #   format_number(1256.95, delimiter: ".", separator: ",") # => "1.256,95"
+        #
+        # @api public
+        # @since 2.0.0
+        def format_number(number, delimiter: DEFAULT_DELIMITER, separator: DEFAULT_SEPARATOR, precision: DEFAULT_PRECISION) # rubocop:disable Layout/LineLength
+          Formatter.call(number, delimiter: delimiter, separator: separator, precision: precision)
+        end
+
+        private
+
+        # Formatter
+        #
+        # @since 2.0.0
+        # @api private
+        class Formatter
+          # Regex to delimit the integer part of a number into groups of three digits.
+          #
+          # @since 2.0.0
+          # @api private
+          DELIMITING_REGEX = /(\d)(?=(\d{3})+$)/
+          private_constant :DELIMITING_REGEX
+
+          # Regex to guess if the number is a integer.
+          #
+          # @since 2.0.0
+          # @api private
+          INTEGER_REGEXP = /\A\d+\z/
+          private_constant :INTEGER_REGEXP
+
+          # @see NumberFormattingHelper#format_number
+          #
+          # @since 2.0.0
+          # @api private
+          def self.call(number, delimiter:, separator:, precision:)
+            number = coerce(number)
+            str = to_str(number, precision)
+            array = parts(str, delimiter)
+
+            array.join(separator)
+          end
+
+          # Coerces the given number or string into a number.
+          #
+          # @since 2.0.0
+          # @api private
+          def self.coerce(number)
+            case number
+            when NilClass
+              raise ArgumentError, "failed to convert #{number.inspect} to number"
+            when ->(n) { n.to_s.match(INTEGER_REGEXP) }
+              Integer(number)
+            else
+              begin
+                Float(number)
+              rescue TypeError
+                raise ArgumentError, "failed to convert #{number.inspect} to float"
+              rescue ArgumentError => e
+                raise e.class, "failed to convert #{number.inspect} to float"
+              end
+            end
+          end
+
+          # Formats the given number as a string.
+          #
+          # @since 2.0.0
+          # @api private
+          def self.to_str(number, precision)
+            case number
+            when Integer
+              number.to_s
+            else
+              ::Kernel.format("%.#{precision}f", number)
+            end
+          end
+
+          # Returns the integer and fractional parts of the given number string.
+          #
+          # @since 2.0.0
+          # @api private
+          def self.parts(string, delimiter)
+            integer_part, fractional_part = string.split(DEFAULT_SEPARATOR)
+            [delimit_integer(integer_part, delimiter), fractional_part].compact
+          end
+
+          # Delimits the given integer part of a number.
+          #
+          # @param integer_part [String] integer part of the number
+          # @param delimiter [String] hundreds delimiter
+          #
+          # @return [String] delimited integer string
+          #
+          # @since 2.0.0
+          # @api private
+          def self.delimit_integer(integer_part, delimiter)
+            integer_part.gsub(DELIMITING_REGEX) { |digit| "#{digit}#{delimiter}" }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "json"
+require "set"
+
+module Hanami
+  class View
+    module Helpers
+      module TagHelper
+        # Tag builder returned from {TagHelper#tag}.
+        #
+        # @see TagHelper#tag
+        #
+        # @api public
+        # @since 2.0.0
+        class TagBuilder
+          # @api private
+          # @since 2.0.0
+          HTML_VOID_ELEMENTS = %i(
+            area base br col embed hr img input keygen link meta param source track wbr
+          ).to_set
+
+          # @api private
+          # @since 2.0.0
+          SVG_SELF_CLOSING_ELEMENTS = %i(
+            animate animateMotion animateTransform circle ellipse line path polygon polyline rect set stop use view
+          ).to_set
+
+          # @api private
+          # @since 2.0.0
+          ATTRIBUTE_SEPARATOR = " "
+
+          # @api private
+          # @since 2.0.0
+          BOOLEAN_ATTRIBUTES = %w(
+            allowfullscreen allowpaymentrequest async autofocus
+            autoplay checked compact controls declare default
+            defaultchecked defaultmuted defaultselected defer
+            disabled enabled formnovalidate hidden indeterminate
+            inert ismap itemscope loop multiple muted nohref
+            nomodule noresize noshade novalidate nowrap open
+            pauseonexit playsinline readonly required reversed
+            scoped seamless selected sortable truespeed
+            typemustmatch visible
+          ).to_set
+          BOOLEAN_ATTRIBUTES.merge(BOOLEAN_ATTRIBUTES.map(&:to_sym))
+          BOOLEAN_ATTRIBUTES.freeze
+
+          # @api private
+          # @since 2.0.0
+          ARIA_PREFIXES = ["aria", :aria].to_set.freeze
+
+          # @api private
+          # @since 2.0.0
+          DATA_PREFIXES = ["data", :data].to_set.freeze
+
+          # @api private
+          # @since 2.0.0
+          TAG_TYPES = {}.tap do |hsh|
+            BOOLEAN_ATTRIBUTES.each { |attr| hsh[attr] = :boolean }
+            DATA_PREFIXES.each { |attr| hsh[attr] = :data }
+            ARIA_PREFIXES.each { |attr| hsh[attr] = :aria }
+            hsh.freeze
+          end
+
+          # @api private
+          # @since 2.0.0
+          PRE_CONTENT_STRINGS = Hash.new { "" }
+          PRE_CONTENT_STRINGS[:textarea]  = "\n"
+          PRE_CONTENT_STRINGS["textarea"] = "\n"
+          PRE_CONTENT_STRINGS.freeze
+
+          # @api private
+          # @since 2.0.0
+          attr_reader :inflector
+
+          # @api private
+          # @since 2.0.0
+          def initialize(inflector:)
+            @inflector = inflector
+          end
+
+          # Transforms a Hash into HTML Attributes, ready to be interpolated into
+          # ERB.
+          #
+          # @example
+          #   <input <%= tag.attributes(type: :text, aria: { label: "Search" }) %> >
+          #   # => <input type="text" aria-label="Search">
+          #
+          # @api public
+          # @since 2.0.0
+          def attributes(**attributes)
+            tag_options(**attributes).to_s.strip.html_safe
+          end
+
+          # Returns a `<p>` HTML tag.
+          #
+          # @api public
+          # @since 2.0.0
+          def p(*args, **options, &block)
+            tag_string(:p, *args, **options, &block)
+          end
+
+          # @api private
+          # @since 2.0.0
+          def tag_string(name, content = nil, **options)
+            content = yield if block_given?
+            self_closing = SVG_SELF_CLOSING_ELEMENTS.include?(name)
+
+            if (HTML_VOID_ELEMENTS.include?(name) || self_closing) && content.nil?
+              "<#{inflector.dasherize(name.to_s)}#{tag_options(**options)}#{self_closing ? " />" : ">"}".html_safe
+            else
+              content_tag_string(inflector.dasherize(name.to_s), content || "", **options)
+            end
+          end
+
+          # @api private
+          # @since 2.0.0
+          def content_tag_string(name, content, **options)
+            tag_options = tag_options(**options) unless options.empty?
+
+            name = EscapeHelper.escape_xml_name(name)
+            content = EscapeHelper.escape_html(content)
+
+            "<#{name}#{tag_options}>#{PRE_CONTENT_STRINGS[name]}#{content}</#{name}>".html_safe
+          end
+
+          # @api private
+          # @since 2.0.0
+          def tag_options(**options)
+            return if options.none?
+
+            output = +""
+
+            options.each_pair do |key, value|
+              type = TAG_TYPES[key]
+
+              if type == :data && value.is_a?(Hash)
+                value.each_pair do |k, v|
+                  next if v.nil?
+
+                  output << ATTRIBUTE_SEPARATOR
+                  output << prefix_tag_option(key, k, v)
+                end
+              elsif type == :aria && value.is_a?(Hash)
+                value.each_pair do |k, v|
+                  next if v.nil?
+
+                  case v
+                  when Array, Hash
+                    tokens = TagHelper.build_tag_values(v)
+                    next if tokens.none?
+
+                    v = EscapeHelper.escape_join(tokens, " ")
+                  else
+                    v = v.to_s
+                  end
+
+                  output << ATTRIBUTE_SEPARATOR
+                  output << prefix_tag_option(key, k, v)
+                end
+              elsif type == :boolean
+                if value
+                  output << ATTRIBUTE_SEPARATOR
+                  output << boolean_tag_option(key)
+                end
+              elsif !value.nil?
+                output << ATTRIBUTE_SEPARATOR
+                output << tag_option(key, value)
+              end
+            end
+
+            output unless output.empty?
+          end
+
+          # @api private
+          # @since 2.0.0
+          def boolean_tag_option(key)
+            %(#{key}="#{key}")
+          end
+
+          # @api private
+          # @since 2.0.0
+          def tag_option(key, value)
+            key = EscapeHelper.escape_xml_name(key)
+
+            case value
+            when Array, Hash
+              value = TagHelper.build_tag_values(value) if key.to_s == "class"
+              value = EscapeHelper.escape_join(value, " ")
+            when Regexp
+              value = EscapeHelper.escape_html(value.source)
+            else
+              value = EscapeHelper.escape_html(value)
+            end
+            value = value.gsub('"', "&quot;") if value.include?('"')
+
+            %(#{key}="#{value}")
+          end
+
+          private
+
+          # @api private
+          # @since 2.0.0
+          def method_missing(called, *args, **options, &block)
+            tag_string(called, *args, **options, &block)
+          end
+
+          # @api private
+          # @since 2.0.0
+          def respond_to_missing?(*args)
+            true
+          end
+
+          # @api private
+          # @since 2.0.0
+          def prefix_tag_option(prefix, key, value)
+            key = "#{prefix}-#{inflector.dasherize(key.to_s)}"
+
+            unless value.is_a?(String) || value.is_a?(Symbol)
+              value = value.to_json
+            end
+
+            tag_option(key, value)
+          end
+        end
+      end
+    end
+  end
+end