hanami-view 2.1.0.rc1 → 2.1.0.rc2

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

@@ -12,26 +12,26 @@ module Hanami
         # @see TagHelper#tag
         #
         # @api public
-        # @since 2.0.0
+        # @since 2.1.0
         class TagBuilder
           # @api private
-          # @since 2.0.0
+          # @since 2.1.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
+          # @since 2.1.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
+          # @since 2.1.0
           ATTRIBUTE_SEPARATOR = " "
 
           # @api private
-          # @since 2.0.0
+          # @since 2.1.0
           BOOLEAN_ATTRIBUTES = %w(
             allowfullscreen allowpaymentrequest async autofocus
             autoplay checked compact controls declare default
@@ -47,15 +47,15 @@ module Hanami
           BOOLEAN_ATTRIBUTES.freeze
 
           # @api private
-          # @since 2.0.0
+          # @since 2.1.0
           ARIA_PREFIXES = ["aria", :aria].to_set.freeze
 
           # @api private
-          # @since 2.0.0
+          # @since 2.1.0
           DATA_PREFIXES = ["data", :data].to_set.freeze
 
           # @api private
-          # @since 2.0.0
+          # @since 2.1.0
           TAG_TYPES = {}.tap do |hsh|
             BOOLEAN_ATTRIBUTES.each { |attr| hsh[attr] = :boolean }
             DATA_PREFIXES.each { |attr| hsh[attr] = :data }
@@ -64,18 +64,18 @@ module Hanami
           end
 
           # @api private
-          # @since 2.0.0
+          # @since 2.1.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
+          # @since 2.1.0
           attr_reader :inflector
 
           # @api private
-          # @since 2.0.0
+          # @since 2.1.0
           def initialize(inflector:)
             @inflector = inflector
           end
@@ -88,7 +88,7 @@ module Hanami
           #   # => <input type="text" aria-label="Search">
           #
           # @api public
-          # @since 2.0.0
+          # @since 2.1.0
           def attributes(**attributes)
             tag_options(**attributes).to_s.strip.html_safe
           end
@@ -96,13 +96,13 @@ module Hanami
           # Returns a `<p>` HTML tag.
           #
           # @api public
-          # @since 2.0.0
+          # @since 2.1.0
           def p(*args, **options, &block)
             tag_string(:p, *args, **options, &block)
           end
 
           # @api private
-          # @since 2.0.0
+          # @since 2.1.0
           def tag_string(name, content = nil, **options)
             content = yield if block_given?
             self_closing = SVG_SELF_CLOSING_ELEMENTS.include?(name)
@@ -115,7 +115,7 @@ module Hanami
           end
 
           # @api private
-          # @since 2.0.0
+          # @since 2.1.0
           def content_tag_string(name, content, **options)
             tag_options = tag_options(**options) unless options.empty?
 
@@ -126,7 +126,7 @@ module Hanami
           end
 
           # @api private
-          # @since 2.0.0
+          # @since 2.1.0
           def tag_options(**options)
             return if options.none?
 
@@ -174,13 +174,13 @@ module Hanami
           end
 
           # @api private
-          # @since 2.0.0
+          # @since 2.1.0
           def boolean_tag_option(key)
             %(#{key}="#{key}")
           end
 
           # @api private
-          # @since 2.0.0
+          # @since 2.1.0
           def tag_option(key, value)
             key = EscapeHelper.escape_xml_name(key)
 
@@ -201,19 +201,19 @@ module Hanami
           private
 
           # @api private
-          # @since 2.0.0
+          # @since 2.1.0
           def method_missing(called, *args, **options, &block)
             tag_string(called, *args, **options, &block)
           end
 
           # @api private
-          # @since 2.0.0
+          # @since 2.1.0
           def respond_to_missing?(*args)
             true
           end
 
           # @api private
-          # @since 2.0.0
+          # @since 2.1.0
           def prefix_tag_option(prefix, key, value)
             key = "#{prefix}-#{inflector.dasherize(key.to_s)}"
 

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

@@ -30,7 +30,7 @@ module Hanami
       #   end
       #
       # @api public
-      # @since 2.0.0
+      # @since 2.1.0
       module TagHelper
         extend self
 
@@ -64,7 +64,7 @@ module Hanami
         #   <% end %>
         #
         # @api public
-        # @since 2.0.0
+        # @since 2.1.0
         def tag
           tag_builder
         end
@@ -111,7 +111,7 @@ module Hanami
         # @see #tag
         #
         # @api public
-        # @since 2.0.0
+        # @since 2.1.0
         def link_to(content, url = nil, **attributes, &block)
           if block
             raise ArgumentError if url && content
@@ -145,7 +145,7 @@ module Hanami
         #   # => "123 foo bar"
         #
         # @api public
-        # @since 2.0.0
+        # @since 2.1.0
         def token_list(*args)
           tokens = build_tag_values(*args).flat_map { |value|
             safe = value.html_safe?
@@ -158,13 +158,13 @@ module Hanami
         # @see #token_list
         #
         # @api public
-        # @since 2.0.0
+        # @since 2.1.0
         def class_names(...)
           token_list(...)
         end
 
         # @api private
-        # @since 2.0.0
+        # @since 2.1.0
         def build_tag_values(*args)
           tag_values = []
 
@@ -185,7 +185,7 @@ module Hanami
         end
 
         # @api private
-        # @since 2.0.0
+        # @since 2.1.0
         def tag_builder
           @tag_builder ||= begin
             TagBuilder.new(inflector: tag_builder_inflector)
@@ -193,7 +193,7 @@ module Hanami
         end
 
         # @api private
-        # @since 2.0.0
+        # @since 2.1.0
         def tag_builder_inflector
           if respond_to?(:_context)
             return _context.inflector

data/lib/hanami/view/html.rb

@@ -2,6 +2,10 @@
 
 module Hanami
   class View
+    # HTML-focused behavior for strings intended to be output in templates.
+    #
+    # @api public
+    # @since 2.1.0
     module HTML
       # A string that has been marked as "HTML safe", ensuring that it is not automatically escaped
       # when used in HTML view templates.
@@ -12,16 +16,17 @@ module Hanami
       # @see String#html_safe
       #
       # @api public
-      # @since 2.0.0
+      # @since 2.1.0
       class SafeString < String
         # @api public
-        # @since 2.0.0
+        # @since 2.1.0
         def initialize(string)
           super(string)
           freeze
         end
 
         # @api private
+        # @since 2.1.0
         private def initialize_copy(other)
           super
           freeze
@@ -30,7 +35,7 @@ module Hanami
         # @return [true]
         #
         # @api public
-        # @since 2.0.0
+        # @since 2.1.0
         def html_safe?
           true
         end
@@ -38,7 +43,7 @@ module Hanami
         # @return [self]
         #
         # @api public
-        # @since 2.0.0
+        # @since 2.1.0
         def html_safe
           self
         end
@@ -46,14 +51,14 @@ module Hanami
         # @return [self]
         #
         # @api public
-        # @since 2.0.0
+        # @since 2.1.0
         def to_s
           self
         end
       end
 
       # @api private
-      # @since 2.0.0
+      # @since 2.1.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.
@@ -61,7 +66,7 @@ module Hanami
         # @return [Hanami::View::HTML::SafeString]
         #
         # @api public
-        # @since 2.0.0
+        # @since 2.1.0
         def html_safe
           Hanami::View::HTML::SafeString.new(self)
         end
@@ -85,7 +90,7 @@ class Object
   # @return [false]
   #
   # @api public
-  # @since 2.0.0
+  # @since 2.1.0
   def html_safe?
     false
   end
@@ -95,7 +100,7 @@ class Numeric
   # @return [true]
   #
   # @api public
-  # @since 2.0.0
+  # @since 2.1.0
   def html_safe?
     true
   end

data/lib/hanami/view/html_safe_string_buffer.rb

@@ -25,7 +25,7 @@ module Hanami
     # @see Hanami::View::SlimAdapter::Template
     #
     # @api private
-    # @since 2.0.0
+    # @since 2.1.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`.

data/lib/hanami/view/part.rb

@@ -13,8 +13,10 @@ module Hanami
     # @see https://dry-rb.org/gems/dry-view/parts/
     #
     # @api public
+    # @since 2.1.0
     class Part
       # @api private
+      # @since 2.1.0
       CONVENIENCE_METHODS = %i[
         format
         context
@@ -31,6 +33,7 @@ module Hanami
       # @return [Symbol] name
       #
       # @api public
+      # @since 2.1.0
       attr_reader :_name
 
       # The decorated value. This is the value returned from the exposure.
@@ -44,6 +47,7 @@ module Hanami
       # @return [Object] value
       #
       # @api public
+      # @since 2.1.0
       attr_reader :_value
 
       # The current rendering
@@ -51,12 +55,16 @@ module Hanami
       # @return [Rendering]
       #
       # @api private
+      # @since 2.1.0
       attr_reader :_rendering
 
-      # Determins a part name (when initialized without one). Intended for use
-      # only while unit testing Parts.
+      # Determines a part name (when initialized without one). Intended for internal use only while
+      # unit testing Parts.
+      #
+      # @return [String]
       #
       # @api private
+      # @since 2.1.0
       def self.part_name(inflector)
         name ? inflector.underscore(inflector.demodulize(name)) : "part"
       end
@@ -68,6 +76,7 @@ module Hanami
       # @param rendering [Rendering] the current rendering
       #
       # @api public
+      # @since 2.1.0
       def initialize(
         rendering: RenderingMissing.new,
         name: self.class.part_name(rendering.inflector),
@@ -78,7 +87,7 @@ module Hanami
         @_rendering = rendering
       end
 
-      # The template format for the current render environment.
+      # Returns the template format for the current rendering.
       #
       # @overload _format
       #   Returns the format.
@@ -89,11 +98,12 @@ module Hanami
       # @return [Symbol] format
       #
       # @api public
+      # @since 2.1.0
       def _format
         _rendering.format
       end
 
-      # The context object for the current render environment
+      # Returns the context object for the current rendering.
       #
       # @overload _context
       #   Returns the context.
@@ -104,10 +114,13 @@ module Hanami
       # @return [Context] context
       #
       # @api public
+      # @since 2.1.0
       def _context
         _rendering.context
       end
 
+      # rubocop:disable Naming/UncommunicativeMethodParamName
+
       # Renders a new partial with the part included in its locals.
       #
       # @overload _render(partial_name, as: _name, **locals, &block)
@@ -124,7 +137,7 @@ module Hanami
       # @return [String] rendered partial
       #
       # @api public
-      # rubocop:disable Naming/UncommunicativeMethodParamName
+      # @since 2.1.0
       def _render(partial_name, as: _name, **locals, &block)
         _rendering.partial(partial_name, _rendering.scope({as => self}.merge(locals)), &block)
       end
@@ -145,26 +158,28 @@ module Hanami
       # @return [Hanami::View::Scope] scope
       #
       # @api public
+      # @since 2.1.0
       def _scope(scope_name = nil, **locals)
         _rendering.scope(scope_name, {_name => self}.merge(locals))
       end
 
-      # Returns a string representation of the value
+      # Returns a string representation of the value.
       #
       # @return [String]
       #
       # @api public
+      # @since 2.1.0
       def to_s
         _value.to_s
       end
 
-      # Builds a new a part with the given parameters
+      # Builds a new a part with the given parameters.
       #
-      # This is helpful for manually constructing a new part object that
-      # maintains the current render environment.
+      # This is helpful for manually constructing a new part object that maintains the current
+      # rendering.
       #
-      # However, using `.decorate` is preferred for declaring attributes that
-      # should also be decorated as parts.
+      # However, using `.decorate` is preferred for declaring attributes that should also be
+      # decorated as parts.
       #
       # @see DecoratedAttributes::ClassInterface#decorate
       #
@@ -174,6 +189,7 @@ module Hanami
       # @param options[Hash<Symbol, Object>] other options to provide when initializing the new part
       #
       # @api public
+      # @since 2.1.0
       def new(klass = self.class, name: _name, value: _value, **options)
         klass.new(
           name: name,
@@ -183,11 +199,12 @@ module Hanami
         )
       end
 
-      # Returns a string representation of the part
+      # Returns a string representation of the part.
       #
       # @return [String]
       #
       # @api public
+      # @since 2.1.0
       def inspect
         %(#<#{self.class.name} name=#{_name.inspect} value=#{_value.inspect}>)
       end

data/lib/hanami/view/part_builder.rb

@@ -2,12 +2,13 @@
 
 module Hanami
   class View
-    # Decorates exposure values with matching parts
+    # Decorates exposure values with matching parts.
     #
-    # @api private
+    # @api public
+    # @since 2.1.0
     class PartBuilder
       class << self
-        # Decorates an exposure value
+        # Decorates an exposure value.
         #
         # @param name [Symbol] exposure name
         # @param value [Object] exposure value
@@ -15,7 +16,8 @@ module Hanami
         #
         # @return [Hanami::View::Part] decorated value
         #
-        # @api private
+        # @api public
+        # @since 2.1.0
         def call(name, value, as: nil, rendering:)
           builder = value.respond_to?(:to_ary) ? :build_collection_part : :build_part
 

data/lib/hanami/view/path.rb

@@ -5,11 +5,16 @@ require "pathname"
 module Hanami
   class View
     # @api private
+    # @since 2.1.0
     class Path
       include Dry::Equalizer(:dir, :root)
 
+      # @api private
+      # @since 2.1.0
       attr_reader :dir, :root
 
+      # @api private
+      # @since 2.1.0
       def self.[](path)
         if path.is_a?(self)
           path
@@ -18,21 +23,30 @@ module Hanami
         end
       end
 
+      # @api private
+      # @since 2.1.0
       def initialize(dir, root: dir)
         @dir = Pathname(dir)
         @root = Pathname(root)
       end
 
       # Searches for a template using a wildcard for the engine extension
+      #
+      # @api private
+      # @since 2.1.0
       def lookup(prefix, name, format)
         glob = dir.join(prefix, "#{name}.#{format}.*")
         Dir[glob].first
       end
 
+      # @api private
+      # @since 2.1.0
       def chdir(dirname)
         self.class.new(dir.join(dirname), root: root)
       end
 
+      # @api private
+      # @since 2.1.0
       def to_s
         dir.to_s
       end

data/lib/hanami/view/rendered.rb

@@ -4,22 +4,25 @@ require "dry/core/equalizer"
 
 module Hanami
   class View
-    # Output of a View rendering
+    # The output of a view rendering.
     #
     # @api public
     # @since 2.1.0
     class Rendered
       include Dry::Equalizer(:output, :locals)
 
-      # Returns the rendered view
+      # Returns the rendered view output.
       #
       # @return [String]
       #
+      # @see to_s
+      # @see to_str
+      #
       # @api public
       # @since 2.1.0
       attr_reader :output
 
-      # Returns the hash of locals used to render the view
+      # Returns the hash of locals used to render the view output.
       #
       # @return [Hash[<Symbol, Hanami::View::Part>] locals hash
       #
@@ -34,7 +37,7 @@ module Hanami
         @locals = locals
       end
 
-      # Returns the local corresponding to the key
+      # Returns the local corresponding to the key.
       #
       # @param name [Symbol] local key
       #
@@ -46,7 +49,7 @@ module Hanami
         locals[name]
       end
 
-      # Returns the rendered view
+      # Returns the rendered view output.
       #
       # @return [String]
       #
@@ -55,9 +58,12 @@ module Hanami
       def to_s
         output
       end
+
+      # @api public
+      # @since 2.1.0
       alias_method :to_str, :to_s
 
-      # Matches given input with the rendered view
+      # Returns true if the given input matches the rendered view output.
       #
       # @param matcher [String, Regexp] matcher
       #
@@ -70,7 +76,7 @@ module Hanami
       end
       alias_method :match, :match?
 
-      # Checks if given string is included in the rendered view
+      # Returns true if given string is included in the rendered view output.
       #
       # @param string [String] string
       #

data/lib/hanami/view/renderer.rb

@@ -5,18 +5,33 @@ require_relative "errors"
 module Hanami
   class View
     # @api private
+    # @since 2.1.0
     class Renderer
+      # @api private
+      # @since 2.1.0
       PARTIAL_PREFIX = "_"
+
+      # @api private
+      # @since 2.1.0
       PATH_DELIMITER = "/"
+
+      # @api private
+      # @since 2.1.0
       CURRENT_PATH_PREFIX = "."
 
+      # @api private
+      # @since 2.1.0
       attr_reader :config, :prefixes
 
+      # @api private
+      # @since 2.1.0
       def initialize(config)
         @config = config
         @prefixes = [CURRENT_PATH_PREFIX]
       end
 
+      # @api private
+      # @since 2.1.0
       def template(name, format, scope, &block)
         old_prefixes = @prefixes.dup
 
@@ -32,6 +47,8 @@ module Hanami
         @prefixes = old_prefixes
       end
 
+      # @api private
+      # @since 2.1.0
       def partial(name, format, scope, &block)
         template(name_for_partial(name), format, scope, &block)
       end