arbre2 2.1.0

data/lib/arbre/rails/layouts.rb

@@ -0,0 +1,126 @@
+module Arbre
+  module Rails
+
+    # Provides a content-template / layout-template construct to be used with Arbre.
+    #
+    # The idea is that the 'content' view defines the type of document to use, through the {ContextMethods#document}
+    # method, and that the 'layout' view/views provide post-processing steps to the document, and subsequently render
+    # the document class.
+    #
+    # == Usage example
+    #
+    # *+app/views/session/new.html.arb+:*
+    #
+    #   document LoginScreen do
+    #     ...
+    #   end
+    #
+    # *+app/views/layouts/application.html.arb+:*
+    #
+    #   layout do
+    #     self.title = "#{self.title} | Application Name"
+    #   end
+    #
+    # In this case, the content template (+session/new.html.arb+) defines that the content document should be a +LoginScreen+
+    # class, and provides a block to customize the screen.
+    #
+    # The layout template (+layouts/application.html.arb+) provides some common steps that should be applied to all pages
+    # using this layout. This block is executed *after* the content customization block.
+    #
+    # == Content block
+    #
+    # The content block that is specified will be passed to the document class' +build+ method, meaning that it can be used
+    # to customize the document in place. However, if the block is not used by the class, it is "instance-exec'd" on the
+    # document instance, so that all documents can be customized in a content template.
+    #
+    # For example, imagine that class +LoginScreen < Arbre::Html::Document+ does not accept or call the block passed into
+    # its +build+ method. The following will still be possible:
+    #
+    # *+app/views/session/new.html.arb+:*
+    #
+    #   document LoginScreen do
+    #     after 'fieldset.password' do
+    #       link forgot_password_path, 'forgot password?'
+    #     end
+    #   end
+    module Layouts
+
+      # Describes a content document and build options.
+      # @api internal
+      class ContentDocument < Struct.new(:klass, :build_arguments, :content_block); end
+
+      ######
+      # ControllerMethods concern
+
+        module ControllerMethods
+
+          protected
+
+          # See {ContextMethods#document} below.
+          # @api internal
+          def arbre_document(klass = nil, *build_arguments, &content_block)
+            @arbre_document = ContentDocument.new(klass, build_arguments, content_block) if klass
+            @arbre_document
+          end
+
+        end
+
+      ######
+      # ContextMethods
+
+        module ContextMethods
+
+          # Obtains and/or sets the current content document.
+          #
+          # @overload document
+          #   Gets an object representing the content document to create. This is mostly for internal use.
+          #
+          # @overload document(klass, *build_arguments, &content_block)
+          #   Specifies a document class and arguments to use. You may optionally customize it using a block.
+          #
+          #   @param [Class] klass            The document class to use.
+          #   @param [Array] build_arguments  Any arguments to pass to the document's +build+ method.
+          #   @param [Proc] content_block     A block to be executed as the content block. See {Layouts above}
+          #                                   for more info.
+          def document(klass = nil, *build_arguments, &content_block)
+            controller.send :arbre_document, klass, *build_arguments, &content_block
+          end
+
+          # Provides a layout block to the current view and appends the current document
+          # to the current arbre element.
+          #
+          # @return [Arbre::Html::Document]  The rendered document.
+          def layout(&layout_block)
+            doc = if document && document.content_block
+              # Use the specified document with the specified content block.
+
+              # Detect whether the block is called.
+              block_called = false
+              content_block = document.content_block
+              doc = append(document.klass, *document.build_arguments) do |*args|
+                block_called = true
+                instance_exec *args, &content_block
+              end
+
+              # Call the block anyway if it hasn't been called yet.
+              doc.instance_exec &document.content_block unless block_called
+              doc
+
+            elsif document
+              # Use the specified document.
+              append document.klass, *document.build_arguments
+            else
+              # Append an empty document.
+              append Arbre::Rails.legacy_document
+            end
+
+            # Run the layout block unless this is an AJAX request.
+            doc.instance_exec &layout_block if layout_block && !request.xhr?
+            doc
+          end
+
+        end
+
+    end
+  end
+end

data/lib/arbre/rails/legacy_document.rb

@@ -0,0 +1,29 @@
+module Arbre
+  module Rails
+
+    # This document adds "legacy" ActionView content to the right places.
+    class LegacyDocument < Html::Document
+
+      def build!
+        super
+
+        head do
+          text_node helpers.content_for(:head)
+        end
+        body do
+          text_node helpers.content_for(:layout)
+        end
+      end
+
+      def to_s
+        if request.xhr?
+          body.content
+        else
+          super
+        end
+      end
+
+    end
+
+  end
+end

data/lib/arbre/rails/rendering.rb

@@ -0,0 +1,76 @@
+module Arbre
+  module Rails
+
+    # Template rendering strategies for Arbre.
+    #
+    # == Partials
+    #
+    # Simply use the method {#partial} instead of +render :partial => '...'+.
+    #
+    # *+edit.html.arb+:*
+    #
+    #   fieldset do
+    #     partial 'fieldset'
+    #   end
+    #
+    # *+_fieldset.html.arb+:*
+    #
+    #   # Note: `self' is the same `self' as in the template above!
+    #   label :something
+    #   text_field :something
+    #
+    # To pass another context than +self+:
+    #
+    # *+edit.html.arb+:*
+    #
+    #   form do |form|
+    #     fieldset do
+    #       partial 'fieldset', context: form
+    #     end
+    #   end
+    #
+    # *+_fieldset.html.arb+:*
+    #
+    #   # Note: `self' is now the form defined in the template above.
+    #   label :something
+    #   text_field :something
+    #
+    module Rendering
+
+      # Inserts a partial into the current flow.
+      #
+      # @param [Hash]     locals
+      #   Extra local variables for the partial.
+      # @option [Element] context
+      #   The context which is used to render the partial. This can be any element, and
+      #   is typically the calling element. The partial template may refer to this as
+      #   +self+.
+      def partial(name, context: self, **locals)
+        render :partial => name, :locals => locals.merge(:arbre_context => context)
+      end
+
+      # Uses the given arguments to perform an ActionView render. If the result is an Arbre
+      # context, instead of treating it as a string, its children are added to the current
+      # element.
+      def render(*args, locals: {}, **options)
+        locals = locals.merge(:arbre_output_context => true)
+        result = helpers.render(*args, locals: locals, **options)
+
+        case result
+        when Arbre::Context
+          # Append all the context's children to the current element. However, watch out as
+          # the children collection is modified during this operation. We'll first create
+          # a copy.
+          current_element.children.concat result.children.to_a
+        when Arbre::Element
+          current_element.children << result
+        else
+          current_element.children << TextNode.from_string(result) if result.length > 0
+        end
+        result
+      end
+
+    end
+
+  end
+end

data/lib/arbre/rails/rspec/arbre_support.rb

@@ -0,0 +1,61 @@
+module Arbre
+  module Rails
+    module RSpec
+
+      # Adds support for an Arbre context.
+      module ArbreSupport
+
+        # Simulates how ArbreTemplateHandler sets up a context, but using the context
+        # build block.
+        def arbre_context
+          @arbre_context ||= Arbre::Context.new(assigns, helpers)
+        end
+        alias_method :arbre, :arbre_context
+
+        # Override to provide default assigns (or define +let(:assigns) {...}+).
+        def assigns
+          @assigns ||= {}
+        end
+
+        # Override to provide default helpers (or define +let(:helpers) {...}+).
+        def helpers
+          @helpers ||= build_helpers
+        end
+
+        def build_helpers
+          helpers = ActionView::Base.new
+
+          # Simulate a default controller & request.
+          allow(helpers).to receive(:controller).and_return(controller)
+          allow(helpers).to receive(:request).and_return(request)
+
+          # Include all application controller's helpers.
+          if defined?(ApplicationController)
+            helpers.singleton_class.send :include, ApplicationController._helpers
+          end
+
+          # Stub asset_path
+          allow(helpers).to receive(:asset_path) { |asset| "/assets/#{asset}" }
+
+          helpers
+        end
+
+        def controller
+          @controller ||= ActionController::Base.new.tap do |controller|
+            controller.request = request
+          end
+        end
+
+        def request
+          @request ||= ActionDispatch::Request.new('rack.input' => '')
+        end
+
+      end
+
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include Arbre::Rails::RSpec::ArbreSupport, arbre: true
+end

data/lib/arbre/rails/rspec.rb

@@ -0,0 +1,2 @@
+require 'arbre/rspec'
+require 'arbre/rails/rspec/arbre_support'

data/lib/arbre/rails/template_handler.rb

@@ -0,0 +1,32 @@
+module Arbre
+  module Rails
+
+    # Template handler capable of re-using an arbre context. If the method or local variable +arbre_context+
+    # yields an Arbre context, it is re-used. Note that this may very well be an element as well. The template
+    # source is executed on the found 'context' or on a new {Arbre::Context} if it was not found.
+    #
+    # @see Partials
+    class TemplateHandler
+
+      # Readable version:
+      #
+      # _arbre_reuse_context = defined?(arbre_context)
+      # _arbre_ctx = _arbre_reuse_context ? arbre_context : Arbre::Context.new(assigns, self)
+      # _arbre_ctx.instance_exec { <template source> }
+      #
+      # if _arbre_reuse_context
+      #   ''
+      # elsif defined?(arbre_output_context)
+      #   _arbre_ctx
+      # else
+      #   _arbre_ctx.to_html
+      # end
+
+      def call(template)
+        "_arbre_reuse_context = defined?(arbre_context); _arbre_ctx = _arbre_reuse_context ? arbre_context : Arbre::Context.new(assigns, self); _arbre_ctx.instance_exec { #{template.source}\n}; _arbre_reuse_context ? '' : defined?(arbre_output_context) ? _arbre_ctx : _arbre_ctx.to_html"
+      end
+
+    end
+
+  end
+end

data/lib/arbre/rails.rb

@@ -0,0 +1,35 @@
+require 'arbre/rails/template_handler'
+require 'arbre/rails/legacy_document'
+require 'arbre/rails/layouts'
+require 'arbre/rails/rendering'
+
+module Arbre
+  module Rails
+    class << self
+      attr_accessor :legacy_document
+      def legacy_document
+        @legacy_document ||= Rails::LegacyDocument
+      end
+    end
+  end
+
+  class Railtie < ::Rails::Railtie
+
+    initializer "arbre.add_autoload_paths" do |app|
+      ActiveSupport::Dependencies.autoload_paths << "#{app.config.root}/app/views/arbre"
+    end
+
+    initializer "arbre.add_layout_support" do
+      ActionController::Base.send :include, Arbre::Rails::Layouts::ControllerMethods
+      Arbre::Context.send :include, Arbre::Rails::Layouts::ContextMethods
+    end
+
+    initializer "arbre.register_template_handler" do
+      ActionView::Template.register_template_handler :arb, Arbre::Rails::TemplateHandler.new
+    end
+
+  end
+
+  Element.send :include, Rails::Rendering
+  Element.send :include, Rails::Layouts
+end

data/lib/arbre/rspec/be_rendered_as_matcher.rb

@@ -0,0 +1,103 @@
+require 'erb'
+
+module Arbre
+  module RSpec
+
+    # Used to match HTML snippets. HTML is canonized as much as possible, so that you don't have to worry about
+    # whitespace or attribute order. Use '(...)' as a wildcard. You may even place text in the wildcard for
+    # readability: '(... some wildcard ...)'.
+    #
+    # == Examples
+    #
+    #   expect('<a href="test" target="_blank"/>').to \
+    #     be_rendered_as('<a target="_blank" href="test" />') # => true
+    #   expect('<div><span></span><sub></sub></div>').to \
+    #     be_rendered_as('<div>(...)</div>') # => true
+    #   expect('<div><span></span><sub></sub></div>').to \
+    #     be_rendered_as('<div>(... a span here ...)<sub></sub></div>') # => true
+    class BeRenderedAsMatcher
+
+      def initialize(expected, escape: true)
+        @expected = expected
+        @escape = escape
+      end
+
+      attr_reader :expected
+
+      def description
+        "be rendered as #{expected}"
+      end
+
+      def matches?(actual)
+        @actual = actual
+
+        regexp = case expected
+        when Regexp then Regexp.new(canonize_html(expected.source))
+        else Regexp.new('^' + Regexp.escape(canonize_html(expected)).gsub(/\\\(\\\.\\\.\\\..*?(?:\\\.\\\.\\\.)?\\\)/, '.+') + '$')
+        end
+
+        html = actual.to_s
+        html = ERB::Util.html_escape(html) if @escape
+        canonize_html(html) =~ regexp
+      end
+
+      def canonize_html(html)
+        html = html.dup
+
+        html.gsub! /(\s*[\n\r]\s*)+/, ' '
+        html.gsub! /^\s+|\s+$/, ''
+        html.gsub! /\s*(\/?>|<)\s*/, '\1'
+
+        # Extract and order attributes.
+        html.gsub! %r|(<[-_:\w].*?>)| do |all|
+          all =~ %r|(<[-_:\w]+\s*)(.*?)(\s*/?>)|
+          _, pre, attributes, post = $~.to_a
+
+          has_wildcard = attributes =~ /\(\.\.\..*?(?:\.\.\.)?\)/ && attributes =~ /\w+/
+          attributes = attributes.gsub(/\(\.\.\..*?(?:\.\.\.)?\)/, '') if has_wildcard
+          attributes = attributes.scan(/(\(\.\.\..*?(?:\.\.\.)?\)|[-_:\w]+(?:=(?:".*?"|'.*?'|\S+))?)/).sort.join(' ')
+          if has_wildcard
+            attributes = "(...)#{attributes}(...)"
+            pre.chomp! ' '
+          end
+
+          "#{pre}#{attributes}#{post}"
+        end
+
+        # Extract and order classes and styles
+        html.gsub! %r[(class|style)="(.*?)"] do |all|
+          all =~ %r[(class|style)="(.*?)"]
+
+          attribute = $1
+          items = $2.strip.split(/(;\s*|\s+)/).reject(&:blank?).sort.join(' ')
+          %[#{attribute}="#{items}"]
+        end
+
+        html
+      end
+
+      def failure_message_for_should
+        <<-MSG.gsub(/^\s{10}/, '')
+          expected that element of type #{@actual.class} would be rendered differently:
+            expected: #{expected.is_a?(Regexp) ? '/' + canonize_html(expected.source) + '/' : canonize_html(expected)} (#{expected.class})
+                 got: #{@actual.nil? ? 'nil' : canonize_html(ERB::Util.html_escape(@actual.to_s))}
+        MSG
+      end
+
+      def failure_message_for_should_not
+        <<-MSG.gsub(/^\s{10}/, '')
+          expected that element of type #{@actual.class} would not be rendered as #{canonize_html(expected)}, but it was:
+            got: #{@actual.nil? ? 'nil' : canonize_html(ERB::Util.html_escape(@actual.to_s))}
+        MSG
+      end
+
+    end
+
+  end
+end
+
+RSpec::Matchers.module_eval do
+  def be_rendered_as(expected, escape: true)
+    Arbre::RSpec::BeRenderedAsMatcher.new(expected, escape: escape)
+  end
+end

data/lib/arbre/rspec/be_scripted_as_matcher.rb

@@ -0,0 +1,68 @@
+module Arbre
+  module RSpec
+
+    # Used to match JS snippets in HTML content. The JS is canonized as much as possible, so that you don't have to
+    # worry about whitespace. Use '(...)' as a wildcard. You may even place text in the wildcard for
+    # readability: '(... some wildcard ...)'.
+    #
+    # == Examples
+    #
+    #   expect(document.body.find_first('javascript')).to be_scripted_as('Flux.Application.initialize()')
+    #   expect(document.body.find_first('javascript')).to be_scripted_as('Flux.Application.initialize((... args ...))')
+    class BeScriptedAsMatcher
+
+      def initialize(expected)
+        @expected = expected
+      end
+
+      attr_reader :expected
+
+      def description
+        "be scripted as #{expected}"
+      end
+
+      def matches?(actual)
+        @actual = actual
+
+        regexp = case expected
+        when Regexp then Regexp.new(canonize_js(expected.source))
+        else Regexp.new('^' + Regexp.escape(canonize_js(expected)).gsub('\(\.\.\.\)', '.+') + '$')
+        end
+
+        canonize_js(actual.content) =~ regexp
+      end
+
+      def canonize_js(js)
+        js = js.dup
+
+        js.gsub! %r|//\s+<!\[CDATA\[[\n\r]+|, ''
+        js.gsub! %r|[\n\r]+//\s+\]\]>|, ''
+
+        js.gsub! /(\s*[\n\r]\s*)+/, ' '
+        js.gsub! /^\s+|\s+$/, ''
+
+        js
+      end
+
+      def failure_message_for_should
+        <<-MSG.gsub(/^\s{10}/, '')
+          expected that element of type #{@actual.class} would be scripted differently:
+            expected: #{expected.is_a?(Regexp) ? '/' + canonize_js(expected.source) + '/' : canonize_js(expected)} (#{expected.class})
+                 got: #{@actual.nil? ? 'nil' : canonize_js(@actual.content)}
+        MSG
+      end
+
+      def failure_message_for_should_not
+        "expected that element of type #{@actual.class} would be not scripted as #{expected}"
+      end
+
+    end
+
+  end
+end
+
+RSpec::Matchers.module_eval do
+  def be_scripted_as(script)
+    Arbre::RSpec::BeScriptedAsMatcher.new(script)
+  end
+end

data/lib/arbre/rspec/contain_script_matcher.rb

@@ -0,0 +1,64 @@
+module Arbre
+  module RSpec
+
+    # Used to match JS snippets in HTML content. The JS is canonized as much as possible, so that you don't have to
+    # worry about whitespace. Use '(...)' as a wildcard. You may even place text in the wildcard for
+    # readability: '(... some wildcard ...)'.
+    #
+    # == Examples
+    #
+    #   expect(document.body).to contain_script('Flux.Application.initialize()')
+    #   expect(document.body).to contain_script('Flux.Application.initialize((... args ...))')
+    class ContainScriptMatcher
+
+      def initialize(expected)
+        @expected = expected
+      end
+
+      attr_reader :expected
+
+      def description
+        "contain script #{expected}"
+      end
+
+      def matches?(actual)
+        @actual = actual
+        canonize_js(actual.to_s).include?(canonize_js(expected))
+      end
+
+      def canonize_js(js)
+        js = js.dup
+
+        js.gsub! %r|//\s+<!\[CDATA\[[\n\r]+|, ''
+        js.gsub! %r|[\n\r]+//\s+\]\]>|, ''
+
+        js.gsub! /(\s*[\n\r]\s*)+/, ' '
+        js.gsub! /^\s+|\s+$/, ''
+
+        js
+      end
+
+      def failure_message_for_should
+        <<-MSG.gsub(/^\s{10}/, '')
+          expected that element of type #{@actual.class} contained script:
+            expected: #{expected.is_a?(Regexp) ? '/' + canonize_js(expected.source) + '/' : canonize_js(expected)} (#{expected.class})
+                 got: #{@actual.nil? ? 'nil' : canonize_js(@actual.to_s)}
+        MSG
+      end
+
+      def failure_message_for_should_not
+        <<-MSG.gsub(/^\s{10}/, '')
+          expected that element of type #{actual.class} would not contain a script:
+            script: #{expected.is_a?(Regexp) ? '/' + canonize_js(expected.source) + '/' : canonize_js(expected)} (#{expected.class})
+        MSG
+      end
+    end
+
+  end
+end
+
+RSpec::Matchers.module_eval do
+  def contain_script(script)
+    Arbre::RSpec::ContainScriptMatcher.new(script)
+  end
+end

data/lib/arbre/rspec.rb

@@ -0,0 +1,3 @@
+require 'arbre/rspec/be_rendered_as_matcher'
+require 'arbre/rspec/be_scripted_as_matcher'
+require 'arbre/rspec/contain_script_matcher'

data/lib/arbre/text_node.rb

@@ -0,0 +1,35 @@
+require 'erb'
+
+module Arbre
+
+  # A 'raw' text node - it just outputs the HTML escaped version of the string it's
+  # built with.
+  class TextNode < Element
+    builder_method :text_node
+
+    # Builds a raw element from a string.
+    def self.from_string(string)
+      new.tap { |node| node.build!(string) }
+    end
+
+    def children
+      @children ||= ElementCollection.new.tap do |children|
+        def children.<<(*) raise NotImplementedError end
+        def children.add(*) raise NotImplementedError end
+        def children.concat(*) raise NotImplementedError end
+      end
+    end
+
+    attr_reader :text
+
+    def build!(text)
+      @text = text.to_s
+    end
+
+    def to_s
+      text
+    end
+
+  end
+
+end

data/lib/arbre/version.rb

@@ -0,0 +1,3 @@
+module Arbre
+  VERSION = "2.1.0"
+end

data/lib/arbre.rb

@@ -0,0 +1,27 @@
+require 'active_support/inflector'
+require 'active_support/dependencies/autoload'
+require 'active_support/core_ext/module/delegation'
+require 'active_support/core_ext/string/output_safety'
+
+module Arbre
+  module Html
+  end
+end
+
+require 'arbre/element'
+require 'arbre/container'
+require 'arbre/context'
+require 'arbre/text_node'
+
+require 'arbre/element_collection'
+require 'arbre/child_element_collection'
+
+require 'arbre/html/attributes'
+require 'arbre/html/class_list'
+require 'arbre/html/querying'
+require 'arbre/html/tag'
+require 'arbre/html/comment'
+require 'arbre/html/html_tags'
+require 'arbre/html/document'
+
+require 'arbre/rails' if defined?(Rails)