PR Checklist

• The PR title follows our guidelines: https://github.com/NativeScript/NativeScript/blob/master/tools/notes/CONTRIBUTING.md#commit-messages. (TODO)
• There is an issue for the bug/feature this PR is for. To avoid wasting your time, it's best to open a suggestion issue first and wait for approval before working on it. (Seems not)
• You have signed the CLA.
• All existing tests are passing: https://github.com/NativeScript/NativeScript/blob/master/tools/notes/DevelopmentWorkflow.md#running-unit-tests-application. (Not sure how to run them)
• Tests for the changes are included - https://github.com/NativeScript/NativeScript/blob/master/tools/notes/WritingUnitTests.md. (TODO)

What is the current behavior?

The current Events system notifies only the direct target of the event (and any global event listeners). Gestures work a little bit differently to other events, as they are optimised for using without redundantly creating extra gesture listeners when existing ones could be reused.

What is the new behavior?

In summary, Events (including gestures) are now based on DOM EventTarget, and fully support capturing, bubbling, and cancelling.

I'll go into detail below.

Event propagation

Below I'll compare the behaviour before (as a refresher) and after this PR.

1. Assume the following app (comments indicate the names of the instances of these classes, for the sake of distinguishing the two):

<!-- rootView -->
<Page>
  <!-- myStack -->
  <StackLayout>
    <!-- myButton -->
    <Button/>
  </StackLayout>
</Page>

2. Notify the following PropertyChangeData:

myButton.notify({
  eventName: 'propertyChange',
  object: myButton,
  propertyName: 'whatever',
  oldValue: 0,
  value: 1,
});

3. Thereafter the following behaviour would be exhibited:

• Before:
  • handles a 'propertyChangeFirst' event on any class-level (global) listeners: Button;
  • handles a 'propertyChange' event on the target itself: myButton;
  • handles a 'propertyChange' event on any class-level (global) listeners: Button .
• After:
  • handles a 'propertyChangeFirst' event on any class-level (global) listeners: Button;
  • handles a 'propertyChange' event on each target in the capturing path: [rootView, myStack];
  • handles a 'propertyChange' event on the target itself: myButton;
  • handles a 'propertyChange' event on each target in the bubbling path: [myStack, rootView];
  • handles a 'propertyChange' event on any class-level (global) listeners: Button.

Performance impact

Not yet measured, but hopefully we can put something together after cutting an early-access release.

Speed

The new Event propagation obviously performs more work than before, but it's still pretty trivial stuff (just walking a linked list of nodes and evaluating for each one whether there are any eligible listeners for the event currently being dispatched).

Memory usage

A little more memory will be used than before, as the callbacks are now wrapped in a DOMEvent instance. I think this is a small cost.

Room for optimisation

I've written this PR first and foremost to be readable, so there is certainly scope to do a second pass on it to optimise any hot paths. I think the algorithms are sound, so any significant savings would likely have to be a culmination of small optimisations.

Events API

Changes to Observable

The following changes were made in order to support class Observer implements EventTarget:

• Observable methods:
  • addEventListener:
    • extra argument: options?: AddEventListenerOptions | boolean
  • off:
    • extra argument: options?: EventListenerOptions | boolean
  • on:
    • extra argument: options?: AddEventListenerOptions | boolean
  • once:
    • extra argument: options?: AddEventListenerOptions | boolean
  • removeEventListener:
    • extra argument: options?: EventListenerOptions | boolean
  • prototype.addEventListener:
    • extra argument: options?: AddEventListenerOptions | boolean
    • wider type for callback: EventListenerOrEventListenerObject | ((data: EventData) => void)
  • prototype.dispatchEvent:
    • added for the first time
  • prototype.notify:
    • extra argument: options?: CustomEventInit
  • prototype.off:
    • extra argument: options?: EventListenerOptions | boolean
  • prototype.on:
    • extra argument: options?: AddEventListenerOptions | boolean
  • prototype.once:
    • extra argument: options?: AddEventListenerOptions | boolean
  • prototype.removeEventListener:
    • extra argument: options?: EventListenerOptions | boolean
    • wider type for callback: EventListenerOrEventListenerObject | ((data: EventData) => void)

The presence of thisArg means that these APIs don't map exactly to DOM, but perhaps due to the various optional params or non-strict mode, TypeScript is satisfied that the class implements EventTarget.

Although the typings claim to support EventListenerOrEventListenerObject, for the sake of backwards compatibility, we handle the callback strictly as if it were (data: EventData) => void - so please don't pass in (event: Event) => void as it won't go well! My hope would be to migrate to the latter in a major version update, however.

You may ask, then "how do I get hold of the DOM Event, then?" if the callback gives you an EventData. See the following section for that.

New features

EventData callbacks are now wrapped in a DOM Event. To access the DOM Event for the currently-running callback, use this API for now (in a future release, as a breaking change, my intention would be to pass the DOM Event instead of the EventData in the callback):

const callback = (data: EventData) => {
  // How to access the DOM Event wrapping a callback:
  //
  // This unstable API guarantees to return you the DOM
  // Event backing the currently-running callback.
  const domEvent = DOMEvent.unstable_currentEvent!;

  // Feel your new DOM powers!
  domEvent.stopPropagation();
};

Propagation of DOM Events can be stopped via calling domEvent.stopPropagation() or domEvent.stopImmediatePropagation() as per the DOM Events spec.

Native effects relating to the event can be cancelled by calling domEvent.preventDefault() as per the DOM Events spec. However, for now, all events are created as non-cancellable, as cancellability will have to be implemented on a case-by-case basis.

Events can be listened for in either the bubbling or capture phases, based on the options passed into Observable.prototype.addEventListener().

Breaking changes

Removal/restriction of some internal APIs

The listener records in Observable, ViewBase, and GesturesObserver were exposed to external consumers - these are now made private, with certain APIs for accessing them removed. I think it is unlikely that these will have been used outside of Core, in any case.

Corrections to EventData and callback typings

In the course of this PR, I fixed many long-incorrect event listener typings and simplified the EventData typings. So all the old mentions of object?: Partial<Observable> are now simply object: Observable. This is a good thing, but may require some adjustments for existing NativeScript projects.

Deprecation notices

I plan to follow up this PR with another one that removes the static EventTarget-like methods, namely:

Observable.addEventListener
Observable.removeEventListener
Observable.off
Observable.on
Observable.once

This is because they deviate from the EventTarget spec while adding little value. The only usage of it in Core is for Application - in a follow-up PR, Application will be refactored into an Observable to remove the need for it. If this functionality is needed for a particular class after all, consider extending that class and overriding the notify method to your needs.

I would hope also to deprecate thisArg, but we will have to discuss how to go about that.