opal-browser 0.2.0.beta1 → 0.2.0

data/opal/browser/delay.rb

@@ -17,8 +17,6 @@ class Delay
     @window = Native.convert(window)
     @after  = time
     @block  = block
-
-    start
   end
 
   # Abort the timeout.
@@ -39,22 +37,42 @@ class Window
   #
   # @return [Delay] the object representing the timeout
   def after(time, &block)
+    Delay.new(@native, time, &block).tap(&:start)
+  end
+
+  # Execute a block after the given seconds, you have to call [#start] on it
+  # yourself.
+  #
+  # @param time [Float] the seconds after it gets called
+  #
+  # @return [Delay] the object representing the timeout
+  def after!(time, &block)
     Delay.new(@native, time, &block)
   end
 end
 
 end
 
+module Kernel
+  # (see Browser::Window#after)
+  def after(time, &block)
+    $window.after(time, &block)
+  end
+
+  # (see Browser::Window#after!)
+  def after!(time, &block)
+    $window.after!(time, &block)
+  end
+end
+
 class Proc
   # (see Browser::Window#after)
   def after(time)
     $window.after(time, &self)
   end
-end
 
-module Kernel
-  # (see Browser::Window#after)
-  def after(time, &block)
-    $window.after(time, &block)
+  # (see Browser::Window#after!)
+  def after!(time)
+    $window.after!(time, &self)
   end
 end

data/opal/browser/dom.rb

@@ -1,4 +1,3 @@
-require 'browser/dom/event'
 require 'browser/dom/node_set'
 require 'browser/dom/node'
 require 'browser/dom/attribute'
@@ -40,14 +39,12 @@ module Kernel
   def DOM(*args, &block)
     if block
       document = args.shift || $document
-      element  = args.shift
-
-      roots = Browser::DOM::Builder.new(document, element, &block).to_a
+      roots    = Browser::DOM::Builder.new(document, &block).to_a
 
       if roots.length == 1
         roots.first
       else
-        Browser::DOM::NodeSet.new(document, roots)
+        Browser::DOM::NodeSet.new(roots)
       end
     else
       what     = args.shift
@@ -74,12 +71,6 @@ end
 module Browser
 
 class Window
-  include DOM::Event::Target
-
-  target {|value|
-    $window if `#{value} == window`
-  }
-
   # Get the {DOM::Document} for this window.
   #
   # @return [DOM::Document]

data/opal/browser/dom/attribute.rb

@@ -4,21 +4,22 @@ module Browser; module DOM
 class Attribute
   include Native
 
-  # Returns true if the attribute is an id.
-  def id?
-    `#@native.isId`
-  end
-
   # @!attribute [r] name
   # @return [String] the name of the attribute
-  def name
-    `#@native.name`
-  end
+  alias_native :name
 
-  # @!attribute [r] value
+  # @!attribute value
   # @return [String] the value of the attribute
-  def value
-    `#@native.value`
+  alias_native :value
+  alias_native :value=
+
+  # Returns true if the attribute is an id.
+  if Browser.supports? 'Attr.isId'
+    alias_native :id?, :isId
+  else
+    def id?
+      name == :id
+    end
   end
 end
 

data/opal/browser/dom/builder.rb

@@ -29,24 +29,19 @@ class Builder
   def self.build(builder, item)
     to_h.each {|klass, block|
       if klass === item
-        break block.call(builder, item)
+        return block.call(builder, item)
       end
     }
+
+    raise ArgumentError, "cannot build unknown item #{item}"
   end
 
   attr_reader :document, :element
 
-  def initialize(document, element = nil, &block)
+  def initialize(document, &block)
     @document = document
-    @element  = element
     @builder  = Paggio::HTML.new(&block)
     @roots    = @builder.each.map { |e| Builder.build(self, e) }
-
-    if @element
-      @roots.each {|root|
-        @element << root
-      }
-    end
   end
 
   def to_a

data/opal/browser/dom/document.rb

@@ -1,34 +1,11 @@
-require 'browser/location'
-
 module Browser; module DOM
 
 class Document < Element
-  def create_element(name, options = {})
-    if ns = options[:namespace]
-      DOM(`#@native.createElementNS(#{ns}, #{name})`)
-    else
-      DOM(`#@native.createElement(name)`)
-    end
-  end
-
-  if Browser.supports? 'Document.view'
-    def window
-      Window.new(`#@native.defaultView`)
-    end
-  elsif Browser.supports? 'Document.window'
-    def window
-      Window.new(`#@native.parentWindow`)
-    end
-  else
-    def window
-      raise NotImplementedError, 'window from document unsupported'
-    end
-  end
-
-  def create_text(content)
-    DOM(`#@native.createTextNode(#{content})`)
-  end
-
+  # Get the first element matching the given ID, CSS selector or XPath.
+  #
+  # @param what [String] ID, CSS selector or XPath
+  #
+  # @return [Element?] the first matching element
   def [](what)
     %x{
       var result = #@native.getElementById(what);
@@ -43,42 +20,129 @@ class Document < Element
 
   alias at []
 
+  # @!attribute [r] body
+  # @return [Element?] the body element of the document
+  def body
+    DOM(`#@native.body`)
+  end
+
+  # Create a new element for the document.
+  #
+  # @param name [String] the node name
+  # @param options [Hash] optional `:namespace` name
+  #
+  # @return [Element]
+  def create_element(name, options = {})
+    if ns = options[:namespace]
+      DOM(`#@native.createElementNS(#{ns}, #{name})`)
+    else
+      DOM(`#@native.createElement(name)`)
+    end
+  end
+
+  # Create a new text node for the document.
+  #
+  # @param content [String] the text content
+  #
+  # @return [Text]
+  def create_text(content)
+    DOM(`#@native.createTextNode(#{content})`)
+  end
+
   def document
     self
   end
 
+  # @!attribute [r] head
+  # @return [Element?] the head element of the document
+  def head
+    DOM(`#@native.getElementsByTagName("head")[0]`)
+  end
+
   def inspect
-    "#<DOM::Document: #{children.inspect}>"
+    "#<DOM::Document>"
   end
 
-  def title
-    `#@native.title`
+  if Browser.supports? 'Event.addListener'
+    def ready(&block)
+      raise ArgumentError, 'no block given' unless block
+
+      return block.call if ready?
+
+      on 'dom:load' do |e|
+        e.off
+
+        block.call
+      end
+    end
+  elsif Browser.supports? 'Event.attach'
+    def ready(&block)
+      raise ArgumentError, 'no block given' unless block
+
+      return block.call if ready?
+
+      on 'ready:state:change' do |e|
+        if ready?
+          e.off
+
+          block.call
+        end
+      end
+    end
+  else
+    # Wait for the document to be ready and call the block.
+    def ready(&block)
+      raise NotImplementedError, 'document ready unsupported'
+    end
   end
 
-  def title=(value)
-    `#@native.title = value`
+  # Check if the document is ready.
+  def ready?
+    `#@native.readyState === "complete"`
   end
 
+  # @!attribute root
+  # @return [Element?] the root element of the document
   def root
     DOM(`#@native.documentElement`)
   end
 
-  def head
-    DOM(`#@native.getElementsByTagName("head")[0]`)
-  end
-
-  def body
-    DOM(`#@native.body`)
+  def root=(element)
+    `#@native.documentElement = #{Native.convert(element)}`
   end
 
+  # @!attribute [r] style_sheets
+  # @return [Array<CSS::StyleSheet>] the style sheets for the document
   def style_sheets
     Native::Array.new(`#@native.styleSheets`) {|e|
       CSS::StyleSheet.new(e)
     }
   end
 
-  def root=(element)
-    `#@native.documentElement = #{Native.convert(element)}`
+  # @!attribute title
+  # @return [String] the document title
+  def title
+    `#@native.title`
+  end
+
+  def title=(value)
+    `#@native.title = value`
+  end
+
+  if Browser.supports? 'Document.view'
+    def window
+      Window.new(`#@native.defaultView`)
+    end
+  elsif Browser.supports? 'Document.window'
+    def window
+      Window.new(`#@native.parentWindow`)
+    end
+  else
+    # @!attribute [r] window
+    # @return [Window] the window for the document
+    def window
+      raise NotImplementedError, 'window from document unsupported'
+    end
   end
 end
 

data/opal/browser/dom/element.rb

@@ -1,10 +1,15 @@
+require 'browser/dom/element/attributes'
+require 'browser/dom/element/data'
 require 'browser/dom/element/position'
 require 'browser/dom/element/offset'
 require 'browser/dom/element/scroll'
 require 'browser/dom/element/size'
 
 require 'browser/dom/element/input'
+require 'browser/dom/element/select'
 require 'browser/dom/element/image'
+require 'browser/dom/element/template'
+require 'browser/dom/element/textarea'
 
 module Browser; module DOM
 
@@ -17,7 +22,7 @@ class Element < Node
     if self == Element
       name = `node.nodeName`.capitalize
 
-      if Element.const_defined?(name)
+      if Element.constants.include?(name)
         Element.const_get(name).new(node)
       else
         super
@@ -33,8 +38,76 @@ class Element < Node
     DOM(value) rescue nil
   }
 
-  alias_native :id
+  if Browser.supports? 'Element.matches'
+    def =~(selector)
+      `#@native.matches(#{selector})`
+    end
+  elsif Browser.supports? 'Element.matches (Opera)'
+    def =~(selector)
+      `#@native.oMatchesSelector(#{selector})`
+    end
+  elsif Browser.supports? 'Element.matches (Internet Explorer)'
+    def =~(selector)
+      `#@native.msMatchesSelector(#{selector})`
+    end
+  elsif Browser.supports? 'Element.matches (Firefox)'
+    def =~(selector)
+      `#@native.mozMatchesSelector(#{selector})`
+    end
+  elsif Browser.supports? 'Element.matches (Chrome)'
+    def =~(selector)
+      `#@native.webkitMatchesSelector(#{selector})`
+    end
+  elsif Browser.loaded? 'Sizzle'
+    def =~(selector)
+      `Sizzle.matchesSelector(#@native, #{selector})`
+    end
+  else
+    # Check whether the element matches the given selector.
+    #
+    # @param selector [String] the CSS selector
+    def =~(selector)
+      raise NotImplementedError, 'selector matching unsupported'
+    end
+  end
 
+  # Query for children with the given XPpaths.
+  #
+  # @param paths [Array<String>] the XPaths to look for
+  #
+  # @return [NodeSet]
+  def /(*paths)
+    NodeSet[paths.map { |path| xpath(path) }]
+  end
+
+  # Get the attribute with the given name.
+  #
+  # @param name [String] the attribute name
+  # @param options [Hash] options for the attribute
+  #
+  # @option options [String] :namespace the namespace for the attribute
+  #
+  # @return [String?]
+  def [](name, options = {})
+    attributes.get(name, options)
+  end
+
+  # Set the attribute with the given name and value.
+  #
+  # @param name [String] the attribute name
+  # @param value [Object] the attribute value
+  # @param options [Hash] the options for the attribute
+  #
+  # @option options [String] :namespace the namespace for the attribute
+  def []=(name, value, options = {})
+    attributes.set(name, value, options)
+  end
+
+  # Add class names to the element.
+  #
+  # @param names [Array<String>] class names to add
+  #
+  # @return [self]
   def add_class(*names)
     classes = class_names + names
 
@@ -45,79 +118,131 @@ class Element < Node
     self
   end
 
-  def remove_class(*names)
-    classes = class_names - names
+  # Get the first node that matches the given CSS selector or XPath.
+  #
+  # @param path_or_selector [String] an XPath or CSS selector
+  #
+  # @return [Node?]
+  def at(path_or_selector)
+    xpath(path_or_selector).first || css(path_or_selector).first
+  end
 
-    if classes.empty?
-      `#@native.removeAttribute('class')`
-    else
-      `#@native.className = #{classes.join ' '}`
-    end
+  # Get the first node matching the given CSS selectors.
+  #
+  # @param rules [Array<String>] the CSS selectors to match with
+  #
+  # @return [Node?]
+  def at_css(*rules)
+    result = nil
 
-    self
+    rules.each {|rule|
+      if result = css(rule).first
+        break
+      end
+    }
+
+    result
   end
 
-  alias_native :class_name, :className
+  # Get the first node matching the given XPath.
+  #
+  # @param paths [Array<String>] the XPath to match with
+  #
+  # @return [Node?]
+  def at_xpath(*paths)
+    result = nil
 
-  def class_names
-    `#@native.className`.split(/\s+/).reject(&:empty?)
+    paths.each {|path|
+      if result = xpath(path).first
+        break
+      end
+    }
+
+    result
   end
 
-  alias attribute attr
+  alias attr []
 
-  def attribute_nodes
-    Native::Array.new(`#@native.attributes`, get: :item) { |e| DOM(e) }
-  end
+  alias attribute []
 
+  # @!attribute [r] attributes
+  # @return [Attributes] the attributes for the element
   def attributes(options = {})
     Attributes.new(self, options)
   end
 
-  def get(name, options = {})
-    if namespace = options[:namespace]
-      `#@native.getAttributeNS(#{namespace.to_s}, #{name.to_s}) || nil`
-    else
-      `#@native.getAttribute(#{name.to_s}) || nil`
-    end
-  end
-
-  def set(name, value, options = {})
-    if namespace = options[:namespace]
-      `#@native.setAttributeNS(#{namespace.to_s}, #{name.to_s}, #{value})`
-    else
-      `#@native.setAttribute(#{name.to_s}, #{value.to_s})`
-    end
+  # @!attribute [r] attribute_nodes
+  # @return [NodeSet] the attribute nodes for the element
+  def attribute_nodes
+    NodeSet[Native::Array.new(`#@native.attributes`, get: :item)]
   end
 
-  alias [] get
-  alias []= set
-
-  alias attr get
-  alias attribute get
-
-  alias get_attribute get
-  alias set_attribute set
+  # @!attribute [r] class_name
+  # @return [String] all the element class names
+  alias_native :class_name, :className
 
-  def key?(name)
-    !!self[name]
+  # @!attribute [r] class_names
+  # @return [Array<String>] all the element class names
+  def class_names
+    `#@native.className`.split(/\s+/).reject(&:empty?)
   end
 
-  def keys
-    attributes_nodesmap(&:name)
+  if Browser.supports? 'Query.css'
+    def css(path)
+      NodeSet[Native::Array.new(`#@native.querySelectorAll(path)`)]
+    rescue
+      NodeSet[]
+    end
+  elsif Browser.loaded? 'Sizzle'
+    def css(path)
+      NodeSet[`Sizzle(path, #@native)`]
+    rescue
+      NodeSet[]
+    end
+  else
+    # Query for children matching the given CSS selector.
+    #
+    # @param selector [String] the CSS selector
+    #
+    # @return [NodeSet]
+    def css(selector)
+      raise NotImplementedError, 'query by CSS selector unsupported'
+    end
   end
 
-  def values
-    attribute_nodes.map(&:value)
-  end
+  # @overload data()
+  #
+  #   Return the data for the element.
+  #
+  #   @return [Data]
+  #
+  # @overload data(hash)
+  #
+  #   Set data on the element.
+  #
+  #   @param hash [Hash] the data to set
+  #
+  #   @return [self]
+  def data(value = nil)
+    data = Data.new(self)
+
+    return data unless value
+
+    if Hash === value
+      data.assign(value)
+    else
+      raise ArgumentError, 'unknown data type'
+    end
 
-  def remove_attribute(name)
-    `#@native.removeAttribute(name)`
+    self
   end
 
-  def size(*inc)
-    Size.new(self, *inc)
-  end
+  alias get_attribute []
+
+  alias get []
 
+  # @!attribute height
+  # @return [Integer] the height of the element
   def height
     size.height
   end
@@ -126,142 +251,133 @@ class Element < Node
     size.height = value
   end
 
-  def width
-    size.width
-  end
-
-  def width=(value)
-    size.width = value
-  end
+  # @!attribute id
+  # @return [String?] the ID of the element
+  def id
+    %x{
+      var id = #@native.id;
 
-  def position
-    Position.new(self)
-  end
-
-  def offset(*values)
-    off = Offset.new(self)
-
-    unless values.empty?
-      off.set(*values)
-    end
-
-    off
-  end
-
-  def offset=(value)
-    offset.set(*value)
+      if (id === "") {
+        return nil;
+      }
+      else {
+        return id;
+      }
+    }
   end
 
-  def scroll
-    Scroll.new(self)
+  def id=(value)
+    `#@native.id = #{value.to_s}`
   end
 
+  # Set the inner DOM of the element using the {Builder}.
   def inner_dom(&block)
+    clear
+
     # FIXME: when block passing is fixed
     doc = document
-    clear; Builder.new(doc, self, &block)
 
-    self
+    self << Builder.new(doc, self, &block).to_a
   end
 
+  # Set the inner DOM with the given node.
+  #
+  # (see #append_child)
   def inner_dom=(node)
-    clear; self << node
-  end
+    clear
 
-  def /(*paths)
-    paths.map { |path| xpath(path) }.flatten.uniq
+    self << node
   end
 
-  def at(path)
-    xpath(path).first || css(path).first
-  end
+  def inspect
+    inspect = name.downcase
 
-  def at_css(*rules)
-    rules.each {|rule|
-      found = css(rule).first
+    if id
+      inspect += '.' + id + '!'
+    end
 
-      return found if found
-    }
+    unless class_names.empty?
+      inspect += '.' + class_names.join('.')
+    end
 
-    nil
+    "#<DOM::Element: #{inspect}>"
   end
 
-  def at_xpath(*paths)
-    paths.each {|path|
-      found = xpath(path).first
+  # @!attribute offset
+  # @return [Offset] the offset of the element
+  def offset(*values)
+    off = Offset.new(self)
 
-      return found if found
-    }
+    unless values.empty?
+      off.set(*values)
+    end
 
-    nil
+    off
   end
 
-  def search(*selectors)
-    NodeSet.new document, selectors.map {|selector|
-      xpath(selector).to_a.concat(css(selector).to_a)
-    }.flatten.uniq
+  def offset=(value)
+    offset.set(*value)
   end
 
-  if Browser.supports? 'Query.css'
-    def css(path)
-      %x{
-        try {
-          var result = #@native.querySelectorAll(path);
-
-          return #{NodeSet.new(document,
-            Native::Array.new(`result`))};
-        }
-        catch(e) {
-          return #{NodeSet.new(document)};
-        }
-      }
-    end
-  elsif Browser.loaded? 'Sizzle'
-    def css(path)
-      NodeSet.new(document, `Sizzle(#{path}, #@native)`)
-    end
-  else
-    def css(selector)
-      raise NotImplementedError, 'query by CSS selector unsupported'
-    end
+  # @!attribute [r] position
+  # @return [Position] the position of the element
+  def position
+    Position.new(self)
   end
 
-  if Browser.supports?('Query.xpath') || Browser.loaded?('wicked-good-xpath')
-    if Browser.loaded? 'wicked-good-xpath'
-      `wgxpath.install()`
-    end
+  # @!attribute [r] scroll
+  # @return [Scroll] the scrolling for the element
+  def scroll
+    Scroll.new(self)
+  end
 
-    def xpath(path)
-      %x{
-        try {
-          var result = (#@native.ownerDocument || #@native).evaluate(path,
-            #@native, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
-
-          return #{NodeSet.new(document,
-            Native::Array.new(`result`, get: :snapshotItem, length: :snapshotLength))};
-        }
-        catch (e) {
-          return #{NodeSet.new(document)};
-        }
-      }
-    end
-  else
-    def xpath(path)
-      raise NotImplementedError, 'query by XPath unsupported'
-    end
+  # Search for all the children matching the given XPaths or CSS selectors.
+  #
+  # @param selectors [Array<String>] mixed list of XPaths and CSS selectors
+  #
+  # @return [NodeSet]
+  def search(*selectors)
+    NodeSet.new selectors.map {|selector|
+      xpath(selector).to_a.concat(css(selector).to_a)
+    }.flatten.uniq
   end
 
+  alias set []=
+
+  alias set_attribute []=
+
+  # @overload style()
+  #
+  #   Return the style for the element.
+  #
+  #   @return [CSS::Declaration]
+  #
+  # @overload style(data)
+  #
+  #   Set the CSS style as string or set of values.
+  #
+  #   @param data [String, Hash] the new style
+  #
+  #   @return [self]
+  #
+  # @overload style(&block)
+  #
+  #   Set the CSS style from a CSS builder DSL.
+  #
+  #   @return [self]
   def style(data = nil, &block)
     style = CSS::Declaration.new(`#@native.style`)
 
     return style unless data || block
 
-    if data.is_a?(String)
+    if String === data
       style.replace(data)
-    elsif data.is_a?(Enumerable)
+    elsif Hash === data
       style.assign(data)
     elsif block
       style.apply(&block)
+    else
+      raise ArgumentError, 'unknown data type'
     end
 
     self
@@ -276,111 +392,81 @@ class Element < Node
       CSS::Declaration.new(`#@native.currentStyle`)
     end
   else
+    # @!attribute [r] style!
+    # @return [CSS::Declaration] get the computed style for the element
     def style!
       raise NotImplementedError, 'computed style unsupported'
     end
   end
 
-  def data(what)
-    if Hash === what
-      unless defined?(`#@native.$data`)
-        `#@native.$data = {}`
-      end
+  # Remove an attribute from the element.
+  #
+  # @param name [String] the attribute name
+  def remove_attribute(name)
+    `#@native.removeAttribute(name)`
+  end
 
-      what.each {|name, value|
-        `#@native.$data[name] = value`
-      }
+  # Remove class names from the element.
+  #
+  # @param names [Array<String>] class names to remove
+  #
+  # @return [self]
+  def remove_class(*names)
+    classes = class_names - names
+
+    if classes.empty?
+      `#@native.removeAttribute('class')`
     else
-      return self["data-#{what}"] if self["data-#{what}"]
+      `#@native.className = #{classes.join ' '}`
+    end
 
-      return unless defined?(`#@native.$data`)
+    self
+  end
 
-      %x{
-        var value = #@native.$data[what];
+  # @!attribute [r] size
+  # @return [Size] the size of the element
+  def size(*inc)
+    Size.new(self, *inc)
+  end
 
-        if (value === undefined) {
-          return nil;
-        }
-        else {
-          return value;
-        }
-      }
-    end
+  # @!attribute width
+  # @return [Integer] the width of the element
+  def width
+    size.width
   end
 
-  if Browser.supports? 'Element.matches'
-    def matches?(selector)
-      `#@native.matches(#{selector})`
-    end
-  elsif Browser.supports? 'Element.matches (Opera)'
-    def matches?(selector)
-      `#@native.oMatchesSelector(#{selector})`
-    end
-  elsif Browser.supports? 'Element.matches (Internet Explorer)'
-    def matches?(selector)
-      `#@native.msMatchesSelector(#{selector})`
-    end
-  elsif Browser.supports? 'Element.matches (Firefox)'
-    def matches?(selector)
-      `#@native.mozMatchesSelector(#{selector})`
-    end
-  elsif Browser.supports? 'Element.matches (Chrome)'
-    def matches?(selector)
-      `#@native.webkitMatchesSelector(#{selector})`
-    end
-  elsif Browser.loaded? 'Sizzle'
-    def matches?(selector)
-      `Sizzle.matchesSelector(#@native, #{selector})`
-    end
-  else
-    def matches?(selector)
-      raise NotImplementedError, 'selector matching unsupported'
-    end
+  def width=(value)
+    size.width = value
   end
 
-  # @abstract
+  # @!attribute [r] window
+  # @return [Window] the window for the element
   def window
     document.window
   end
 
-  def inspect
-    "#<DOM::Element: #{name}>"
-  end
-
-  class Attributes
-    include Enumerable
-
-    attr_reader :namespace
-
-    def initialize(element, options)
-      @element   = element
-      @namespace = options[:namespace]
-    end
-
-    def each(&block)
-      return enum_for :each unless block_given?
-
-      @element.attribute_nodes.each {|attr|
-        yield attr.name, attr.value
-      }
-
-      self
-    end
-
-    def [](name)
-      @element.get_attribute(name, namespace: @namespace)
+  if Browser.supports?('Query.xpath') || Browser.loaded?('wicked-good-xpath')
+    if Browser.loaded? 'wicked-good-xpath'
+      `wgxpath.install()`
     end
 
-    def []=(name, value)
-      @element.set_attribute(name, value, namespace: @namespace)
+    def xpath(path)
+      NodeSet[Native::Array.new(
+        `(#@native.ownerDocument || #@native).evaluate(path,
+           #@native, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null)`,
+        get:    :snapshotItem,
+        length: :snapshotLength)]
+    rescue
+      NodeSet[]
     end
-
-    def merge!(hash)
-      hash.each {|name, value|
-        self[name] = value
-      }
-
-      self
+  else
+    # Query for children matching the given XPath.
+    #
+    # @param path [String] the XPath
+    #
+    # @return [NodeSet]
+    def xpath(path)
+      raise NotImplementedError, 'query by XPath unsupported'
     end
   end
 end