unpoly-rails 1.0.3 → 2.0.0.pre.rc2

data/lib/assets/javascripts/unpoly/event.coffee.erb

@@ -1,445 +0,0 @@
-###**
-Events
-======
-
-Most Unpoly interactions emit DOM events that are prefixed with `up:`.
-
-    document.addEventListener('up:modal:opened', (event) => {
-      console.log('A new modal has just opened!')
-    })
-
-Events often have both present and past forms. For example,
-`up:modal:open` is emitted before a modal starts to open.
-`up:modal:opened` is emitted when the modal has finished its
-opening animation.
-
-\#\#\# Preventing events
-
-You can prevent most present form events by calling `preventDefault()`:
-
-    document.addEventListener('up:modal:open', (event) => {
-      if (event.url == '/evil') {
-        // Prevent the modal from opening
-        event.preventDefault()
-      }
-    })
-
-
-\#\#\# A better way to bind event listeners
-
-Instead of using [`Element#addEventListener()`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener),
-you may find it convenient to use [`up.on()`](/up.on) instead:
-
-    up.on('click', 'button', function(event, button, data) {
-      // button is the clicked element
-      // data is the parsed [`up-data`](/up-data) attribute
-    })
-
-There are some advantages to using `up.on()`:
-
-  - You may pass a selector for [event delegation](https://davidwalsh.name/event-delegate).
-  - The event target is automatically passed as a second argument.
-  - You may register a listener to multiple events by passing a space-separated list of event name (e.g. `"click mousedown"`).
-  - You may register a listener to multiple elements in a single `up.on()` call, by passing a [list](/up.util.isList) of elements.
-  - You may use an [`[up-data]`](/up-data) attribute to [attach structured data](/up.on#attaching-structured-data)
-    to observed elements. If an `[up-data]` attribute is set, its value will automatically be
-    parsed as JSON and passed as a third argument.
-  - Event listeners on [unsupported browsers](/up.browser.isSupported) are silently discarded,
-    leaving you with an application without JavaScript. This is typically preferable to
-    a soup of randomly broken JavaScript in ancient browsers.
-
-@module up.event
-###
-up.event = do ->
-  
-  u = up.util
-  e = up.element
-
-  reset = ->
-    # Resets the list of registered event listeners to the
-    # moment when the framework was booted.
-    for element in [window, document, document.documentElement, document.body]
-      up.EventListener.unbindNonDefault(element)
-
-  ###**
-  Listens to a [DOM event](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model/Events)
-  on `document` or a given element.
-
-  `up.on()` has some quality of life improvements over
-  [`Element#addEventListener()`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener):
-
-  - You may pass a selector for [event delegation](https://davidwalsh.name/event-delegate).
-  - The event target is automatically passed as a second argument.
-  - You may register a listener to multiple events by passing a space-separated list of event name (e.g. `"click mousedown"`)
-  - You may register a listener to multiple elements in a single `up.on()` call, by passing a [list](/up.util.isList) of elements.
-  - You use an [`[up-data]`](/up-data) attribute to [attach structured data](/up.on#attaching-structured-data)
-    to observed elements. If an `[up-data]` attribute is set, its value will automatically be
-    parsed as JSON and passed as a third argument.
-  - Event listeners on [unsupported browsers](/up.browser.isSupported) are silently discarded,
-    leaving you with an application without JavaScript. This is typically preferable to
-    a soup of randomly broken JavaScript in ancient browsers.
-
-  \#\#\# Examples
-
-  The code below will call the listener when a `<a>` is clicked
-  anywhere in the `document`:
-
-      up.on('click', 'a', function(event, element) {
-        console.log("Click on a link %o", element)
-      })
-
-  You may also bind the listener to a given element instead of `document`:
-
-      var form = document.querySelector('form')
-      up.on(form, 'click', function(event, form) {
-        console.log("Click within %o", form)
-      })
-
-  You may also pass both an element and a selector
-  for [event delegation](https://davidwalsh.name/event-delegate):
-
-      var form = document.querySelector('form')
-      up.on(form, 'click', 'a', function(event, link) {
-        console.log("Click on a link %o within %o", link, form)
-      })
-
-  \#\#\# Attaching structured data
-
-  In case you want to attach structured data to the event you're observing,
-  you can serialize the data to JSON and put it into an `[up-data]` attribute:
-
-      <span class='person' up-data='{ "age": 18, "name": "Bob" }'>Bob</span>
-      <span class='person' up-data='{ "age": 22, "name": "Jim" }'>Jim</span>
-
-  The JSON will be parsed and handed to your event handler as a third argument:
-
-      up.on('click', '.person', function(event, element, data) {
-        console.log("This is %o who is %o years old", data.name, data.age)
-      })
-
-  \#\#\# Unbinding an event listener
-
-  `up.on()` returns a function that unbinds the event listeners when called:
-
-      // Define the listener
-      var listener =  function(event) { ... }
-
-      // Binding the listener returns an unbind function
-      var unbind = up.on('click', listener)
-
-      // Unbind the listener
-      unbind()
-
-  There is also a function [`up.off()`](/up.off) which you can use for the same purpose:
-
-      // Define the listener
-      var listener =  function(event) { ... }
-
-      // Bind the listener
-      up.on('click', listener)
-
-      // Unbind the listener
-      up.off('click', listener)
-
-  @function up.on
-  @param {Element|jQuery} [element=document]
-    The element on which to register the event listener.
-
-    If no element is given, the listener is registered on the `document`.
-  @param {string} events
-    A space-separated list of event names to bind to.
-  @param {string} [selector]
-    The selector of an element on which the event must be triggered.
-    Omit the selector to listen to all events with that name, regardless
-    of the event target.
-  @param {Function(event, [element], [data])} listener
-    The listener function that should be called.
-
-    The function takes the affected element as the first argument).
-    If the element has an [`up-data`](/up-data) attribute, its value is parsed as JSON
-    and passed as a second argument.
-  @return {Function()}
-    A function that unbinds the event listeners when called.
-  @stable
-  ###
-  bind = (args...) ->
-    bindNow(args)
-
-  ###**
-  Listens to an event on `document` or a given element.
-  The event handler is called with the event target as a
-  [jQuery collection](https://learn.jquery.com/using-jquery-core/jquery-object/).
-
-  If you're not using jQuery, use `up.on()` instead, which calls
-  event handlers with a native element.
-
-  \#\#\# Example
-
-  ```
-  up.$on('click', 'a', function(event, $link) {
-    console.log("Click on a link with destination %s", $element.attr('href'))
-  })
-  ```
-
-  @function up.$on
-  @param {Element|jQuery} [element=document]
-    The element on which to register the event listener.
-
-    If no element is given, the listener is registered on the `document`.
-  @param {string} events
-    A space-separated list of event names to bind to.
-  @param {string} [selector]
-    The selector of an element on which the event must be triggered.
-    Omit the selector to listen to all events with that name, regardless
-    of the event target.
-  @param {Function(event, [element], [data])} listener
-    The listener function that should be called.
-
-    The function takes the affected element as the first argument).
-    If the element has an [`up-data`](/up-data) attribute, its value is parsed as JSON
-    and passed as a second argument.
-  @return {Function()}
-    A function that unbinds the event listeners when called.
-  @stable
-  ###
-  $bind = (args...) ->
-    bindNow(args, jQuery: true)
-
-  bindNow = (args, options) ->
-    # Silently discard any event handlers that are registered on unsupported
-    # browsers and return a no-op destructor
-    return (->) unless up.browser.isSupported()
-
-    up.EventListener.bind(args, options)
-
-  ###**
-  Unbinds an event listener previously bound with [`up.on()`](/up.on).
-
-  \#\#\# Example
-
-  Let's say you are listing to clicks on `.button` elements:
-
-      var listener = function() { ... }
-      up.on('click', '.button', listener)
-
-  You can stop listening to these events like this:
-
-      up.off('click', '.button', listener)
-
-  Note that you need to pass `up.off()` a reference to the same listener function
-  that was passed to `up.on()` earlier.
-
-  @function up.off
-  @stable
-  ###
-  unbind = (args...) ->
-    up.EventListener.unbind(args)
-
-  ###**
-  Emits a event with the given name and properties.
-
-  The event will be triggered as an event on `document` or on the given element.
-
-  Other code can subscribe to events with that name using
-  [`Element#addEventListener()`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener)
-  or [`up.on()`](/up.on).
-
-  \#\#\# Example
-
-      up.on('my:event', function(event) {
-        console.log(event.foo)
-      })
-
-      up.emit('my:event', { foo: 'bar' })
-      // Prints "bar" to the console
-
-  @function up.emit
-  @param {Element|jQuery} [target=document]
-    The element on which the event is triggered.
-
-    If omitted, the event will be emitted on the `document`.
-  @param {string} eventName
-    The name of the event.
-  @param {Object} [eventProps={}]
-    A list of properties to become part of the event object
-    that will be passed to listeners. Note that the event object
-    will by default include properties like `preventDefault()`
-    or `stopPropagation()`.
-  @param {string|Array} [eventProps.log=false]
-    A message to print to the console when the event is emitted.
-
-    Pass `true` to print a default message
-  @param {Element|jQuery} [eventProps.target=document]
-    The element on which the event is triggered.
-  @stable
-  ###
-  emit = (args...) ->
-    if args[0].addEventListener
-      target = args.shift()
-    else if u.isJQuery(args[0])
-      target = e.get(args.shift())
-
-    eventName = args[0]
-    eventProps = args[1] || {}
-
-    if targetFromProps = u.pluckKey(eventProps, 'target')
-      target = targetFromProps
-    target ?= document
-
-    logEmission(eventName, eventProps)
-
-    event = buildEvent(eventName, eventProps)
-    target.dispatchEvent(event)
-
-    return event
-
-  buildEvent = (name, props) ->
-    event = document.createEvent('Event')
-    event.initEvent(name, true, true) # name, bubbles, cancelable
-    u.assign(event, props)
-
-    # IE11 does not set { defaultPrevented: true } after #preventDefault()
-    # was called on a custom event.
-    # See discussion here: https://stackoverflow.com/questions/23349191
-    if up.browser.isIE11()
-      event.preventDefault = ->
-        Object.defineProperty(event, 'defaultPrevented', get: -> true)
-
-    event
-
-  logEmission = (eventName, eventProps) ->
-    return unless up.log.isEnabled()
-
-    message = u.pluckKey(eventProps, 'log')
-
-    if u.isArray(message)
-      [message, messageArgs...] = message
-    else
-      messageArgs = []
-
-    if u.isString(message)
-      if u.isPresent(eventProps)
-        up.puts "#{message} (%s (%o))", messageArgs..., eventName, eventProps
-      else
-        up.puts "#{message} (%s)", messageArgs..., eventName
-    else if message == true
-      if u.isPresent(eventProps)
-        up.puts 'Event %s (%o)', eventName, eventProps
-      else
-        up.puts 'Event %s', eventName
-
-  ###**
-  [Emits an event](/up.emit) and returns whether no listener
-  has prevented the default action.
-
-  @function up.event.nobodyPrevents
-  @param {string} eventName
-  @param {Object} eventProps
-  @param {string|Array} [eventProps.log]
-  @return {boolean}
-    whether no listener has prevented the default action
-  @experimental
-  ###
-  nobodyPrevents = (args...) ->
-    event = emit(args...)
-    not event.defaultPrevented
-
-  ###**
-  [Emits](/up.emit) the given event and returns a promise
-  that will be fulfilled if no listener has prevented the default action.
-
-  If any listener prevented the default listener
-  the returned promise will never be resolved.
-
-  @function up.event.whenEmitted
-  @param {string} eventName
-  @param {Object} eventProps
-  @param {string|Array} [eventProps.message]
-  @return {Promise}
-  @internal
-  ###
-  whenEmitted = (args...) ->
-    new Promise (resolve, reject) ->
-      if nobodyPrevents(args...)
-        resolve()
-      else
-        reject(new Error("Event #{args[0]} was prevented"))
-
-  ###**
-  Registers an event listener to be called when the user
-  presses the `Escape` key.
-
-  @function up.event.onEscape
-  @param {Function(event)} listener
-    The listener function to register.
-  @return {Function()}
-    A function that unbinds the event listeners when called.
-  @experimental
-  ###
-  onEscape = (listener) ->
-    bind('keydown', 'body', (event) ->
-      if u.escapePressed(event)
-        listener(event)
-    )
-
-  ###**
-  Prevents the event from bubbling up the DOM.
-  Also prevents other event handlers bound on the same element.
-  Also prevents the event's default action.
-
-  \#\#\# Example
-
-      up.on('click', 'link.disabled', function(event) {
-        up.event.halt(event)
-      })
-
-  @function up.event.halt
-  @param {Event} event
-  @experimental
-  ###
-  halt = (event) ->
-    event.stopImmediatePropagation()
-    event.preventDefault()
-
-  ###**
-  @function up.event.consumeAction
-  @internal
-  ###
-  consumeAction = (event) ->
-    # Halt the event chain to stop duplicate processing of this user interaction.
-    halt(event)
-    unless event.type == 'up:action:consumed'
-      # Although we have consumed this action and halted the event chain,
-      # other components might still need to react. E.g. a popup needs to close when
-      # an outside link consumes the user click. So we emit another event for that.
-      emit(event.target, 'up:action:consumed', log: false)
-
-  onReady = (callback) ->
-    # Values are "loading", "interactive" and "completed".
-    # https://developer.mozilla.org/en-US/docs/Web/API/Document/readyState
-    if document.readyState != 'loading'
-      callback()
-    else
-      document.addEventListener('DOMContentLoaded', callback)
-
-  bind 'up:framework:reset', reset
-
-  <% if ENV['JS_KNIFE'] %>knife: eval(Knife.point)<% end %>
-  on: bind # can't name symbols `on` in Coffeescript
-  $on: $bind
-  off: unbind # can't name symbols `off` in Coffeescript
-  emit: emit
-  nobodyPrevents: nobodyPrevents
-  whenEmitted: whenEmitted
-  onEscape: onEscape
-  halt: halt
-  consumeAction: consumeAction
-  onReady: onReady
-
-up.on = up.event.on
-up.$on = up.event.$on
-up.off = up.event.off
-up.$off = up.event.off # it's the same as up.off()
-up.emit = up.event.emit
-
-up.legacy.renamedModule 'bus', 'event'