opal-browser 0.1.0.beta1 → 0.2.0.beta1

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
+  def self.supported?
+    Browser.supports? :MutationObserver
+  end
+
   include Native
 
+  # Encapsulates a recorded change.
   class Record
     include Native
 
+    # @!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`)
@@ -28,6 +52,8 @@ class MutationObserver
       NodeSet.new($document, array)
     end
 
+    # @!attribute [r] removed
+    # @return [NodeSet] the removed nodes
     def removed
       array = if `#@native.removedNodes != null`
         Native::Array.new(`#@native.removedNodes`)
@@ -38,14 +64,28 @@ class MutationObserver
       NodeSet.new($document, 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,5 +1,8 @@
 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
 
@@ -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,23 +38,33 @@ class Node
     end
   end
 
+  # Return true of the other element is the same underlying DOM node.
+  #
+  # @return [Boolean]
   def ==(other)
     `#@native === #{Native.try_convert(other)}`
   end
 
+  # Return true if the node name matches the given name case-insensitively.
+  #
+  # @param name [String] the name to match with
+  #
+  # @return [Boolean]
   def =~(name)
     self.name.downcase == name.downcase
   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
-
-  def <=>(other)
-    raise NotImplementedError
-  end
-
-  def add_child(node)
     if native?(node)
       `#@native.appendChild(node)`
     elsif node.respond_to? :each
@@ -60,26 +78,57 @@ class Node
     self
   end
 
-  def add_next_sibling(node)
-    `#@native.parentNode.insertBefore(node, #@native.nextSibling)`
+  alias add_child <<
 
-    self
+  # 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)
+    if native?(node)
+      `#@native.parentNode.insertBefore(node, #@native.nextSibling)`
+    elsif String === node
+      `#@native.parentNode.insertBefore(
+        #@native.ownerDocument.createTextNode(node), #@native.nextSibling)`
+    else
+      `#@native.parentNode.insertBefore(#{Native.convert(node)},
+        #@native.nextSibling)`
+    end
   end
 
+  # 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)
-    `#@native.parentNode.insertBefore(node, #@native)`
-
-    self
+    if native?(node)
+      `#@native.parentNode.insertBefore(node, #@native)`
+    elsif String === node
+      `#@native.parentNode.insertBefore(
+        #@native.ownerDocument.createTextNode(node), #@native)`
+    else
+      `#@native.parentNode.insertBefore(#{Native.convert(node)}, #@native)`
+    end
   end
 
   alias after add_next_sibling
 
-  def append_to(element)
-    element.add_child(self)
-
-    self
+  # Append the node to the passed one.
+  #
+  # @param node [Node] the node to append to
+  def append_to(node)
+    node.add_child(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
 
@@ -93,52 +142,72 @@ class Node
       parents.pop
     end
 
-    return NodeSet.new(document, parents) unless expression
+    if expression
+      parents.select! {|p|
+        p.matches? expression
+      }
+    end
 
-    NodeSet.new document, parents.select {|p|
-      p.matches?(expression)
-    }
+    NodeSet.new document, parents
   end
 
   alias before add_previous_sibling
 
+  # Remove the node from its parent.
   def remove
-    detach
-    clear
-
-    self
-  end
-
-  def detach
     parent.remove_child(self) if parent
+  end
 
-    self
+  # Remove all the children of the node.
+  def clear
+    children.each(&: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`))
   end
@@ -147,43 +216,51 @@ class Node
     raise NotImplementedError
   end
 
+  # Return true if the node is a comment.
   def comment?
     node_type == COMMENT_NODE
   end
 
+  # @!attribute [r] document
+  # @return [Document?] the document the node is attached to
   def document
-    DOM(`#@native.ownerDocument`)
+    DOM(`#@native.ownerDocument`) if defined?(`#@native.ownerDocument`)
   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(*)
+  # @!attribute inner_html
+  # @return [String] the inner HTML of the node
+  def inner_html
     `#@native.innerHTML`
   end
 
@@ -191,26 +268,24 @@ class Node
     `#@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
 
+  # Check if the node matches the given CSS selector.
+  #
+  # @param expression [String] the CSS selector
   def matches?(expression)
     false
   end
 
+  # @!attribute name
+  # @return [String] the name of the node
   def name
     `#@native.nodeName || nil`
   end
@@ -219,14 +294,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 +326,23 @@ class Node
 
   alias node_name= name=
 
+  # @!attribute [r] node_type
+  # @return [Symbol] the type of the node
   def node_type
     `#@native.nodeType`
   end
 
+  # @!attribute parent
+  # @return [Element?] the parent of the node
   def parent
     DOM(`#@native.parentNode`) if `#@native.parentNode != null`
   end
 
-  def parent= (node)
+  def parent=(node)
     `#@native.parentNode = #{Native.try_convert(node)}`
   end
 
-  def parse (text, options = {})
+  def parse(text, options = {})
     raise NotImplementedError
   end
 
@@ -263,12 +350,16 @@ class Node
     raise NotImplementedError
   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 +372,27 @@ 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)})`
+  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
   end
 
-  alias text inner_text
-  alias text= inner_text=
+  alias text content
+  alias text= content=
 
+  # Return true if the node is a text node.
   def text?
     node_type == TEXT_NODE
   end
@@ -301,6 +403,8 @@ class Node
 
   alias type node_type
 
+  # @!attribute value
+  # @return [String] the value of the node
   def value
     `#@native.nodeValue || nil`
   end
@@ -309,6 +413,7 @@ class Node
     `#@native.nodeValue = value`
   end
 
+  # @private
   def inspect
     "#<DOM::Node: #{name}>"
   end