opal-browser 0.1.0.beta1 → 0.3.1

data/opal/browser/dom/mutation_observer.rb

@@ -1,23 +1,47 @@
 module Browser; module DOM
 
+# A {MutationObserver} is a performant way to observe changes in the DOM,
+# either on the tree, the attributes or data.
+#
+# @see https://developer.mozilla.org/en/docs/Web/API/MutationObserver
 class MutationObserver
-  include Native
+  def self.supported?
+    Browser.supports? :MutationObserver
+  end
+
+  include Native::Wrapper
 
+  # Encapsulates a recorded change.
   class Record
-    include Native
+    include Browser::NativeCachedWrapper
 
+    # @!attribute [r] type
+    # @return [:attributes, :tree, :cdata] the type of the recorded change
     def type
       case `#@native.type`
-      when :attributes    then :attributes
+      when :attributes    then :attribute
       when :childList     then :tree
       when :characterData then :cdata
       end
     end
 
-    def attributes?; type == :attributes; end
-    def tree?;       type == :tree;       end
-    def cdata?;      type == :cdata;      end
+    # Returns true if the change happened on attributes.
+    def attribute?
+      type == :attribute
+    end
+
+    # Returns true if the change happened on the tree.
+    def tree?
+      type == :tree
+    end
 
+    # Returns true if the change happened in a CDATA section.
+    def cdata?
+      type == :cdata
+    end
+
+    # @!attribute [r] added
+    # @return [NodeSet] the added nodes
     def added
       array = if `#@native.addedNodes != null`
         Native::Array.new(`#@native.addedNodes`)
@@ -25,9 +49,11 @@ class MutationObserver
         []
       end
 
-      NodeSet.new($document, array)
+      NodeSet[array]
     end
 
+    # @!attribute [r] removed
+    # @return [NodeSet] the removed nodes
     def removed
       array = if `#@native.removedNodes != null`
         Native::Array.new(`#@native.removedNodes`)
@@ -35,17 +61,31 @@ class MutationObserver
         []
       end
 
-      NodeSet.new($document, array)
+      NodeSet[array]
     end
 
+    # @!attribute [r] target
+    # @return [Node] the node the mutation affected
     def target
       DOM(`#@native.target`)
     end
 
+    # @!attribute [r] old
+    # @return [String] the old value
     alias_native :old, :oldValue
-    alias_native :attribute, :attributeName
+
+    # @!attribute [r] name
+    # @return [String] the name of the attribute
+    alias_native :name, :attributeName
+
+    # @!attribute [r] namespace
+    # @return [String] the namespace of the attribute
+    alias_native :namespace, :attributeNamespace
   end
 
+  # Create a new MutationObserver with the given block.
+  #
+  # @yieldparam records [Array<Record>] the recorded changes
   def initialize(&block)
     %x{
       var func = function(records) {
@@ -56,6 +96,22 @@ class MutationObserver
     super(`new window.MutationObserver(func)`)
   end
 
+  # Observe the given target with the given options.
+  #
+  # The supported options are:
+  #
+  # + **children** - whether to observe changes on the children
+  #   of the target or not
+  # + **tree** - whether to observe changes on the whole subtree
+  #   or not
+  # + **attributes** - whether to observe changes to attributes or not,
+  #   if the value is `:old` the old value will be saved
+  # + **cdata** - whether to observe changes to CDATA sections or not,
+  #   if the value is `:old` the old value will be saved
+  # + **filter** - array of attribute names to observe
+  #
+  # @param target [DOM::Node, native] the node to observe
+  # @param options [Hash?] the options
   def observe(target, options = nil)
     unless options
       options = {
@@ -71,10 +127,14 @@ class MutationObserver
     self
   end
 
+  # Empty the observer queue and return its contents.
+  #
+  # @return [Array<Record>]
   def take
     `#@native.takeRecords()`.map { |r| Record.new(r) }
   end
 
+  # Disconnect the observer, thus stopping observing any changes.
   def disconnect
     `#@native.disconnect()`
   end

data/opal/browser/dom/node.rb

@@ -1,7 +1,10 @@
 module Browser; module DOM
 
+# Abstract class for all DOM node types.
+#
+# @see https://developer.mozilla.org/en-US/docs/Web/API/Node
 class Node
-  include Native
+  include Browser::NativeCachedWrapper
 
   ELEMENT_NODE                = 1
   ATTRIBUTE_NODE              = 2
@@ -16,6 +19,11 @@ class Node
   DOCUMENT_FRAGMENT_NODE      = 11
   NOTATION_NODE               = 12
 
+  # Wrap a native DOM node.
+  #
+  # @param value [native] the native DOM node
+  #
+  # @return [Node]
   def self.new(value)
     if self == Node
       @classes ||= [nil, Element, Attribute, Text, CDATA, nil, nil, nil, Comment, Document, nil, DocumentFragment]
@@ -30,58 +38,156 @@ class Node
     end
   end
 
-  def ==(other)
-    `#@native === #{Native.try_convert(other)}`
-  end
-
-  def =~(name)
-    self.name.downcase == name.downcase
+  def initialize(node)
+    raise ArgumentError, "Please ensure that #initialize of #{self.class} accepts one argument" unless node
+    super
   end
 
+  # Return true of the other element is the same underlying DOM node.
+  #
+  # @return [Boolean]
+  def ==(other)
+    `#@native === #{Native.convert(other)}`
+  end
+
+  # Initialize a new node after `#dup` or `#clone`.
+  #
+  # This method is not to be called directly. Use `Node#dup` or
+  # `Node#clone`.
+  #
+  # This method creates a deep detached clone of a DOM subtree to be used
+  # in the same document. The new node will have all events detached.
+  def initialize_copy(old)
+    set_native_reference `#{old.to_n}.cloneNode(true)`
+  end
+
+  # Append a child to the node.
+  #
+  # When passing a {String} a text node will be created.
+  #
+  # When passing an Object that responds to #each, every yielded element
+  # will be added following the same logic.
+  #
+  # @param node [String, Node, #each, #to_n] the node to append
+  #
+  # @return [self]
   def <<(node)
-    add_child(node)
-  end
+    if Opal.respond_to? node, :each
+      node.each { |n| self << n }
+      return self
+    elsif Opal.respond_to? node, :to_dom
+      node = node.to_dom(document)
+    end
 
-  def <=>(other)
-    raise NotImplementedError
+    unless native?(node)
+      if String === node
+        node = `#@native.ownerDocument.createTextNode(node)`
+      else
+        node = Native.convert(node)
+      end
+    end
+
+    `#@native.appendChild(node)`
+
+    self
   end
 
-  def add_child(node)
-    if native?(node)
+  def >>(node)
+    if Opal.respond_to? node, :each
+      node.each { |n| self >> n }
+      return self
+    elsif Opal.respond_to? node, :to_dom
+      node = node.to_dom(document)
+    end
+
+    unless native?(node)
+      if String === node
+        node = `#@native.ownerDocument.createTextNode(node)`
+      else
+        node = Native.convert(node)
+      end
+    end
+
+    if `#@native.firstChild == null`
       `#@native.appendChild(node)`
-    elsif node.respond_to? :each
-      node.each { |n| add_child(n) }
-    elsif String === node
-      `#@native.appendChild(#@native.ownerDocument.createTextNode(node))`
     else
-      `#@native.appendChild(#{Native.convert(node)})`
+      `#@native.insertBefore(node, #@native.firstChild)`
     end
 
     self
   end
 
-  def add_next_sibling(node)
-    `#@native.parentNode.insertBefore(node, #@native.nextSibling)`
+  def add_child(node = nil, &block)
+    unless node
+      node = DOM(&block)
+    end
 
-    self
+    self << node
   end
 
-  def add_previous_sibling(node)
-    `#@native.parentNode.insertBefore(node, #@native)`
+  # Add the passed node after this one.
+  #
+  # When passing a {String} a text node will be created.
+  #
+  # @param node [String, Node, #to_n] the node to add
+  def add_next_sibling(node = nil, &block)
+    unless node
+      node = DOM(&block)
+    end
+    node = node.to_dom(document) if Opal.respond_to? node, :to_dom
 
-    self
+    unless native?(node)
+      if String === node
+        node = `#@native.ownerDocument.createTextNode(node)`
+      else
+        node = Native.convert(node)
+      end
+    end
+
+    `#@native.parentNode.insertBefore(node, #@native.nextSibling)`
   end
 
-  alias after add_next_sibling
+  # Add the passed node before this one.
+  #
+  # When passing a {String} a text node will be created.
+  #
+  # @param node [String, Node, #to_n] the node to add
+  def add_previous_sibling(node = nil, &block)
+    unless node
+      node = DOM(&block)
+    end
+    node = node.to_dom(document) if Opal.respond_to? node, :to_dom
 
-  def append_to(element)
-    element.add_child(self)
+    unless native?(node)
+      if String === node
+        node = `#@native.ownerDocument.createTextNode(node)`
+      else
+        node = Native.convert(node)
+      end
+    end
 
+    `#@native.parentNode.insertBefore(node, #@native)`
+  end
+
+  alias after add_next_sibling
+
+  # Append the node to the passed one.
+  #
+  # @param node [Node] the node to append to
+  def append_to(node)
+    node << self
     self
   end
 
+  # Get an array of ancestors.
+  #
+  # Passing a selector will select the ancestors matching it.
+  #
+  # @param expression [String] the selector to use as filter
+  #
+  # @return [NodeSet]
   def ancestors(expression = nil)
-    return NodeSet.new(document) unless parent
+    return NodeSet[] unless parent
 
     parents = [parent]
 
@@ -93,124 +199,146 @@ class Node
       parents.pop
     end
 
-    return NodeSet.new(document, parents) unless expression
+    if expression
+      parents.select! { |p| p =~ expression }
+    end
 
-    NodeSet.new document, parents.select {|p|
-      p.matches?(expression)
-    }
+    NodeSet.new(parents)
+  end
+
+  def attached?
+    `#@native.isConnected`
   end
 
   alias before add_previous_sibling
 
+  # Remove the node from its parent.
   def remove
-    detach
-    clear
-
+    parent.remove_child(self) if parent
     self
   end
 
-  def detach
-    parent.remove_child(self) if parent
-
-    self
+  # Remove all the children of the node.
+  def clear
+    children.remove
   end
 
-  def clear; end
+  # @!attribute content
+  # @return [String] the inner text content of the node
+  if Browser.supports? 'Element.textContent'
+    def content
+      `#@native.textContent`
+    end
 
-  def remove_child(element)
-    `#@native.removeChild(#{Native.try_convert(element)})`
+    def content=(value)
+      `#@native.textContent = #{value}`
+    end
+  elsif Browser.supports? 'Element.innerText'
+    def content
+      `#@native.innerText`
+    end
 
-    self
-  end
+    def content=(value)
+      `#@native.innerText = #{value}`
+    end
+  else
+    def content
+      raise NotImplementedError, 'node text content unsupported'
+    end
 
-  def clear
-    children.each(&:remove)
+    def content=(value)
+      raise NotImplementedError, 'node text content unsupported'
+    end
   end
 
   def blank?
     raise NotImplementedError
   end
 
+  # Return true if the node is a CDATA section.
   def cdata?
     node_type == CDATA_SECTION_NODE
   end
 
+  # @!attribute [r] child
+  # @return [Node?] the first child of the node
   def child
     children.first
   end
 
+  # @!attribute children
+  # @return [NodeSet] the children of the node
   def children
-    NodeSet.new(document, Native::Array.new(`#@native.childNodes`))
+    NodeSet[Native::Array.new(`#@native.childNodes`)]
   end
 
   def children=(node)
     raise NotImplementedError
   end
 
+  # Return true if the node is a comment.
   def comment?
     node_type == COMMENT_NODE
   end
 
+  # Return true if the node is a custom element.
+  def custom?
+    false
+  end
+
+  # @!attribute [rw] document
+  # @return [Document?] the document the node is attached to
   def document
-    DOM(`#@native.ownerDocument`)
+    DOM(`#@native.ownerDocument`) if defined?(`#@native.ownerDocument`)
   end
 
+  # Detach a node and transfer it to another document.
+  def document=(new_document)
+    `#{Native.try_convert(new_document, new_document)}.adoptNode(#@native)`
+  end
+
+  # Return true if the node is a document.
   def document?
     node_type == DOCUMENT_NODE
   end
 
+  # Return true if the node is an element.
   def elem?
     node_type == ELEMENT_NODE
   end
 
   alias element? elem?
 
+  # @!attribute [r] element_children
+  # @return [NodeSet] all the children which are elements
   def element_children
     children.select(&:element?)
   end
 
   alias elements element_children
 
+  # @!attribute [r] first_element_child
+  # @return [Element?] the first element child
   def first_element_child
     element_children.first
   end
 
+  # Return true if the node is a document fragment.
   def fragment?
     node_type == DOCUMENT_FRAGMENT_NODE
   end
 
-  def hash
-    # TODO: implement this properly
-  end
-
-  def inner_html(*)
-    `#@native.innerHTML`
-  end
-
-  def inner_html=(value)
-    `#@native.innerHTML = #{value}`
-  end
-
-  def inner_text(*)
-    `#@native.textContent`
-  end
-
-  alias content inner_text
-
-  def inner_text=(value)
-    `#@native.textContent = #{value}`
-  end
-
-  alias content= inner_text=
+  alias inner_text content
+  alias inner_text= content=
 
+  # @!attribute [r] last_element_child
+  # @return [Element?] the last element child
   def last_element_child
     element_children.last
   end
 
-  def matches?(expression)
-    false
-  end
-
+  # @!attribute name
+  # @return [String] the name of the node
   def name
     `#@native.nodeName || nil`
   end
@@ -219,14 +347,22 @@ class Node
     `#@native.nodeName = #{value.to_s}`
   end
 
+  # @!attribute [r] namespace
+  # @return [String] the namespace of the node
   def namespace
     `#@native.namespaceURI || nil`
   end
 
+  # @!attribute next
+  # @return [Node?] the next sibling of the node
   def next
     DOM(`#@native.nextSibling`) if `#@native.nextSibling != null`
   end
 
+  alias next= add_next_sibling
+
+  # @!attribute [r] next_element
+  # @return [Element?] the next element sibling of the node
   def next_element
     current = self.next
 
@@ -243,19 +379,31 @@ class Node
 
   alias node_name= name=
 
+  # @!attribute [r] node_type
+  # @return [Symbol] the type of the node
   def node_type
     `#@native.nodeType`
   end
 
+  # @!attribute outer_html
+  # @return [String] the simulated outer html of the node
+  def outer_html
+    div = $document.create_element("DIV")
+    div << self.dup
+    div.inner_html
+  end
+
+  # @!attribute parent
+  # @return [Element?] the parent of the node
   def parent
     DOM(`#@native.parentNode`) if `#@native.parentNode != null`
   end
 
-  def parent= (node)
-    `#@native.parentNode = #{Native.try_convert(node)}`
+  def parent=(node)
+    `#@native.parentNode = #{Native.convert(node)}`
   end
 
-  def parse (text, options = {})
+  def parse(text, options = {})
     raise NotImplementedError
   end
 
@@ -263,12 +411,24 @@ class Node
     raise NotImplementedError
   end
 
+  # Prepend the node to the passed one.
+  #
+  # @param node [Node] the node to prepend to
+  def prepend_to(node)
+    node >> self
+    self
+  end
+
+  # @!attribute previous
+  # @return [Node?] the previous sibling of the node
   def previous
     DOM(`#@native.previousSibling`) if `#@native.previousSibling != null`
   end
 
   alias previous= add_previous_sibling
 
+  # @!attribute [r] previous_element
+  # @return [Element?] the previous element sibling of the node
   def previous_element
     current = self.previous
 
@@ -281,16 +441,40 @@ class Node
 
   alias previous_sibling previous
 
-  # TODO: implement for NodeSet
+  # Remove the given node from the children of this node.
+  def remove_child(node)
+    `#@native.removeChild(#{Native.try_convert(node)})`
+    self
+  end
+
+  # Replace the node with the given one.
+  #
+  # @todo implement for NodeSet
+  #
+  # @param node [Node] the node to replace with
+  # @return [Node] the passed node
   def replace(node)
-    `#@native.parentNode.replaceChild(#@native, #{Native.try_convert(node)})`
+    node = node.to_dom(document) if Opal.respond_to? node, :to_dom
 
-    node
+    unless native?(node)
+      if String === node
+        node = `#@native.ownerDocument.createTextNode(node)`
+      else
+        node = Native.convert(node)
+      end
+    end
+
+    `#@native.parentNode.replaceChild(node, #@native)`
+
+    DOM(node)
   end
 
-  alias text inner_text
-  alias text= inner_text=
+  alias replace_with replace
+
+  alias text content
+  alias text= content=
 
+  # Return true if the node is a text node.
   def text?
     node_type == TEXT_NODE
   end
@@ -301,6 +485,8 @@ class Node
 
   alias type node_type
 
+  # @!attribute value
+  # @return [String] the value of the node
   def value
     `#@native.nodeValue || nil`
   end
@@ -309,6 +495,7 @@ class Node
     `#@native.nodeValue = value`
   end
 
+  # @private
   def inspect
     "#<DOM::Node: #{name}>"
   end