bowser 0.4.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ce8d7cc946f87f6ff13c2f734fe21374a41a30c5
-  data.tar.gz: 8f5e88a218400a259cafc0fb5bf5c5c083fa3aa5
+  metadata.gz: c8764d8fafbc1b0bceb01df46a44ef1c97957c38
+  data.tar.gz: 0f92be9feadace2fad0b02138476a823e49b440f
 SHA512:
-  metadata.gz: cbf88b08d8fde0e49c923d09eaf10a190b5bb52ecab4ab70c6ad3c6b0ff95e68d74bf054cd5d8246836a5134eda8dea1754528270240be45b6bc4eb868da4ac1
-  data.tar.gz: 77d638123b06602ace4cb47b434906ec010aaf6ea858ef4b8821c359b890c9d5d529aeba9fb59734f00028baa0c85d4cbc06a47dd68292a6d643694f564001db
+  metadata.gz: 5d5e3db8ed89a6bd2fcab026ebc4fca1b705d95118c51571e3d5951d831bdbff9cdcc41a2132b2e1e86e71cd26ad4416412a78dede2dbcfc7dea1e68e78c2fc4
+  data.tar.gz: a1da66808e31e6ddca3b7a6de2f39146f14263f782521389eb9be80db57849585634052985e0a2ee0df1645125d674fe4d3c5d4ac0d5471c3f935dca2001e61a

data/.travis.yml

@@ -1,13 +1,8 @@
 language: ruby
 rvm:
-  - 2.2.5
-  - 2.3.1
-  - 2.4.1
-  - jruby-9.0.5.0
-  - jruby-9.1.1.0
+  - 2.2
+  - 2.3
+  - 2.4
+  - jruby-9.1.14.0
 before_install:
-  - wget https://s3.amazonaws.com/travis-phantomjs/phantomjs-2.0.0-ubuntu-12.04.tar.bz2
-  - tar -xjf phantomjs-2.0.0-ubuntu-12.04.tar.bz2
-  - sudo rm -rf /usr/local/phantomjs/bin/phantomjs
-  - sudo mv phantomjs /usr/local/phantomjs/bin/phantomjs
   - gem install bundler

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## Version 0.5.0
+
+- IndexedDB support (#22)
+- ServiceWorker support (#5)
+- Subscript operators (`[]` and `[]=`) to get/set HTML attributes on `Element`
+- Added `HTTP::Response#ok?` to align with [`Response.ok`](https://developer.mozilla.org/en-US/docs/Web/API/Response/ok)
+
 ## Version 0.3.0
 
 - Fix bug with falsy JS values as element properties

data/lib/bowser/version.rb

@@ -1,3 +1,3 @@
 module Bowser
-  VERSION = "0.4.3"
+  VERSION = "0.5.0"
 end

data/opal/bowser.rb

@@ -3,6 +3,3 @@ require 'bowser/event'
 require 'bowser/event_target'
 require 'bowser/window'
 require 'bowser/document'
-
-module Bowser
-end

data/opal/bowser/delegate_native.rb

@@ -1,6 +1,14 @@
 module Bowser
   module DelegateNative
-    # Fall back to native properties.
+    # Fall back to native properties. If the message sent to this element is not
+    # recognized, it checks to see if it is a property of the native element. It
+    # also checks for variations of the message name, such as:
+    #
+    #   :supported? => [:supported, :isSupported]
+    #
+    # If a property with the specified message name is found and it is a
+    # function, that function is invoked with `args`. Otherwise, the property
+    # is returned as is.
     def method_missing message, *args, &block
       property_name = property_for_message(message)
       property = `#@native[#{property_name}]`

data/opal/bowser/document.rb

@@ -11,10 +11,13 @@ module Bowser
 
     module_function
 
+    # @return [Bowser::Element] the body element of the current document
     def body
       @body ||= Element.new(`#@native.body`)
     end
 
+    # @return [Bowser::Element?] the first element that matches the given CSS
+    #   selector or `nil` if no elements match
     def [] css
       native = `#@native.querySelector(css)`
       if `#{native} === null`
@@ -24,6 +27,10 @@ module Bowser
       end
     end
 
+    # Create an element of the specified type
+    #
+    # @param type [String] the type of element to create
+    # @example Bowser.document.create_element('div')
     def create_element type
       Element.new(`document.createElement(type)`)
     end
@@ -31,6 +38,7 @@ module Bowser
 
   module_function
 
+  # @return [Document] the browser's document object
   def document
     Document
   end

data/opal/bowser/element.rb

@@ -3,6 +3,7 @@ require 'bowser/file_list'
 require 'bowser/delegate_native'
 
 module Bowser
+  # Wrap a native DOM element
   class Element
     include EventTarget
     include DelegateNative
@@ -23,23 +24,37 @@ module Bowser
       element
     end
 
+    # @param native [JS] The native DOM element to wrap
     def initialize native
       @native = native
     end
 
-    def inner_dom= node
+    # Replace all child elements with the given element
+    #
+    # @param element [Bowser::Element] The Bowser element with which to replace
+    #   this element's contents
+    def inner_dom= element
       clear
-      append node
+      append element
     end
 
+    # The contents of this element as an HTML string
+    #
+    # @return [String] the HTML representation of this element's contents
     def inner_html
       `#@native.innerHTML`
     end
 
+    # Use the supplied HTML string to replace this element's contents
+    #
+    # @param html [String] the HTML with which to replace this elements contents
     def inner_html= html
       `#@native.innerHTML = html`
     end
 
+    # This element's direct child elements
+    #
+    # @return [Array<Bowser::Element>] list of this element's children
     def children
       elements = []
 
@@ -53,10 +68,17 @@ module Bowser
       elements
     end
 
+    # Determine whether this element has any contents
+    #
+    # @return [Boolean] true if the element has no children, false otherwise
     def empty?
       `#@native.children.length === 0`
     end
 
+    # Remove all contents from this element. After this call, `empty?` will
+    # return `true`.
+    #
+    # @return [Bowser::Element] self
     def clear
       if %w(input textarea).include? type
         `#@native.value = null`
@@ -69,29 +91,49 @@ module Bowser
       self
     end
 
+    # Remove the specified child element
+    #
+    # @param child [Bowser::Element] the child element to remove
     def remove_child child
       `#@native.removeChild(child['native'] ? child['native'] : child)`
     end
 
+    # This element's type. For example: "div", "span", "p"
+    #
+    # @return [String] the HTML tag name for this element
     def type
       `#@native.nodeName`.downcase
     end
 
+    # Append the specified element as a child element
+    #
+    # @param element [Bowser::Element, JS] the element to insert
     def append node
       `#@native.appendChild(node['native'] ? node['native'] : node)`
       self
     end
 
-    # Form input methods
+    # Methods for <input /> elements
+
+    # A checkbox's checked status
+    #
+    # @return [Boolean] true if the checkbox is checked, false otherwise
     def checked?
       `!!#@native.checked`
     end
 
-    # Convenience for when you only need a single file
+    # Get the currently selected file for this input. This is only useful for
+    # file inputs without the `multiple` property set.
+    #
+    # @return [Bowser::File] the file selected by the user
     def file
       files.first
     end
 
+    # Get the currently selected files for this input. This is only useful for
+    # file inputs with the `multiple` property set.
+    #
+    # @return [Bowser::FileList] the currently selected files for this input
     def files
       FileList.new(`#@native.files`)
     end
@@ -100,6 +142,17 @@ module Bowser
       `#@native === #{other.to_n}`
     end
 
+    def []= attribute, value
+      `#@native.setAttribute(#{attribute}, #{value})`
+    end
+
+    def [] attribute
+      `#@native.getAttribute(#{attribute})`
+    end
+
+    # The native representation of this element.
+    #
+    # @return [JS] the native element wrapped by this object.
     def to_n
       @native
     end

data/opal/bowser/event.rb

@@ -1,47 +1,76 @@
 module Bowser
+  # Wrapper for JS events
   class Event
+    # @param [JS] the native event to wrap
     def initialize native
       @native = native
     end
 
+    # Prevent the runtime from executing this event's default behavior. For
+    # example, prevent navigation after clicking a link.
+    #
+    # @return [Bowser::Event] self
     def prevent
       `#@native.preventDefault()`
       self
     end
 
+    # Prevent the runtime from bubbling this event up the hierarchy. This is
+    # typically used to keep an event local to the element on which it was
+    # triggered, such as keeping a click event on a button from unintentionally
+    # triggering a handler on a parent element.
+    #
+    # @return self
     def stop_propagation
       `#@native.stopPropagation()`
       self
     end
 
+    # @return [Boolean] true if `prevent` has been called on this event, false
+    #   otherwise
     def prevented?
       `#@native.defaultPrevented`
     end
 
+    # @return [Boolean] true if the Meta/Command/Windows key was pressed when
+    #   this event fired, false otherwise
     def meta?
       `#@native.metaKey`
     end
 
+    # @return [Boolean] true if the Shift key was pressed when this event fired,
+    #   false otherwise
     def shift?
       `#@native.shiftKey`
     end
 
+    # @return [Boolean] true if the Ctrl key was pressed when this event fired,
+    #   false otherwise
     def ctrl?
       `#@native.ctrlKey`
     end
 
+    # @return [Boolean] true if the Alt key was pressed when this event fired,
+    #   false otherwise
     def alt?
       `#@native.altKey`
     end
 
+    # The target for this event
+    #
+    # @return [Bowser::Element] the element on which this event was triggered
+    # @todo Handle non-DOM events here
     def target
       Element.new(`#@native.target`)
     end
 
+    # @return [Numeric] the key code associated with this event. Only useful for
+    #   keyboard-based events.
     def code
       `#@native.keyCode`
     end
 
+    # Return properties on the event not covered by Ruby methods.
     def method_missing name, *args
       property = name.gsub(/_[a-z]/) { |match| match[-1, 1].upcase }
       value = `#@native[property]`
@@ -55,6 +84,7 @@ module Bowser
       end
     end
 
+    # @return [JS] the native event wrapped by this object.
     def to_n
       @native
     end

data/opal/bowser/event_target.rb

@@ -2,6 +2,12 @@ require 'bowser/event'
 
 module Bowser
   module EventTarget
+    # Add the block as a handler for the specified event name. Will use either
+    # `addEventListener` or `addListener` if they exist.
+    #
+    # @param event_name [String] the name of the event
+    # @return [Proc] the block to pass to `off` to remove this handler
+    # @yieldparam event [Bowser::Event] the event object
     def on event_name, &block
       wrapper = proc { |event| block.call Event.new(event) }
 
@@ -16,6 +22,10 @@ module Bowser
       wrapper
     end
 
+    # Remove an event handler
+    #
+    # @param event_name [String] the name of the event
+    # @block the handler to remove, as returned from `on`
     def off event_name, &block
       if `#@native.removeEventListener !== undefined`
         `#@native.removeEventListener(event_name, block)`

data/opal/bowser/file_list.rb

@@ -5,6 +5,7 @@ module Bowser
   class FileList
     include Enumerable
 
+    # @param native [JS] the native FileList object to wrap
     def initialize native
       @native = `#{native} || []`
       @files = length.times.each_with_object([]) { |index, array|
@@ -12,54 +13,72 @@ module Bowser
       }
     end
 
+    # @param index [Integer] the index of the file in the list
+    # @return [Bowser::FileList::File] the file at the specified index
     def [] index
       @files[index]
     end
 
+    # @return [Integer] the number of files in this list
     def length
       `#@native.length`
     end
     alias size length
 
+    # Call the given block for each file in the list
+    #
+    # @yieldparam file [Bowser::FileList::File]
     def each &block
       @files.each do |file|
         block.call file
       end
     end
 
+    # Convert this FileList into an array
     def to_a
       @files.dup # Don't return a value that can mutate our internal state
     end
     alias to_ary to_a
 
+    # @return [String] a string representation of this FileList
     def to_s
       @files.to_s
     end
 
+    # An individual item in a FileList
     class File
       attr_reader :data
 
+      # @param native [JS] the native File object to wrap
       def initialize native
         @native = native
         @data = nil
       end
 
+      # @return [String] the filename
       def name
         `#@native.name`
       end
 
+      # @return [Integer] the size of this file on disk
       def size
         `#@native.size`
       end
 
+      # @return [String] the MIME type of the file, detected by the browser
       def type
         `#@native.type`
       end
 
+      # @return [Time] the timestamp of the file
       def last_modified
         `#@native.lastModifiedDate`
       end
 
+      # Read the file from disk into memory
+      #
+      # @return [Promise] a promise that resolves when finished loading and
+      #   rejects if an error occurs while loading.
       def read
         promise = Promise.new
         reader = FileReader.new
@@ -79,10 +98,16 @@ module Bowser
         promise
       end
 
+      # Convert to the native object
+      #
+      # @return [JS.HTMLElement] the underlying native element
       def to_n
         @native
       end
 
+      # The object that reads the file from disk.
+      #
+      # @api private
       class FileReader
         include EventTarget