javascript/NativeScript
1
0
Fork 0
mirror of https://github.com/NativeScript/NativeScript.git synced 2025-11-05 13:26:48 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: DOM events

Browse Source 
BREAKING CHANGE
This commit is contained in:
shirakaba
2022-11-12 22:40:18 +09:00
parent ed14e24283
commit 7a276df09c
13 changed files with 1089 additions and 575 deletions
Download Patch File Download Diff File Expand all files Collapse all files

379
packages/core/data/dom-events/dom-event.ts Normal file
View File

@@ -0,0 +1,379 @@
import type { EventData, ListenerEntry, Observable } from '../observable/index';
import type { ViewBase } from '../../ui/core/view-base';
const timeOrigin = Date.now();
/**
* Purely a performance utility. We fall back to an empty array on various
* optional accesses, so reusing the same one and treating it as immutable
* avoids unnecessary allocations on a relatively hot path of the library.
*/
const emptyArray = [] as const;
export class DOMEvent {
readonly NONE = 0;
readonly CAPTURING_PHASE = 1;
readonly AT_TARGET = 2;
readonly BUBBLING_PHASE = 3;
/**
* Returns true or false depending on how event was initialized. Its return
* value does not always carry meaning, but true can indicate that part of
* the operation during which event was dispatched, can be canceled by
* invoking the preventDefault() method.
*/
readonly cancelable: boolean = false;
/**
* Returns true or false depending on how event was initialized. True if
* event goes through its target's ancestors in reverse tree order, and
* false otherwise.
*/
readonly bubbles: boolean = false;
private _canceled = false;
/** @deprecated Setting this value does nothing. */
cancelBubble = false;
/**
* Returns true or false depending on how event was initialized. True if
* event invokes listeners past a ShadowRoot node that is the root of its
* target, and false otherwise.
*/
readonly composed: boolean;
/**
* Returns true if event was dispatched by the user agent, and false
* otherwise.
* For now, all NativeScript events will have isTrusted: false.
*/
readonly isTrusted: boolean = false;
/** @deprecated Use defaultPrevented instead. */
get returnValue() {
return !this.defaultPrevented;
}
/**
* Returns the event's timestamp as the number of milliseconds measured
* relative to the time origin.
*/
readonly timeStamp: DOMHighResTimeStamp = timeOrigin - Date.now();
/** @deprecated */
get srcElement(): Observable | null {
return this.target;
}
/**
* Returns true if preventDefault() was invoked successfully to indicate
* cancelation, and false otherwise.
*/
get defaultPrevented() {
return this._canceled;
}
private _eventPhase: 0 | 1 | 2 | 3 = this.NONE;
/**
* Returns the event's phase, which is one of NONE, CAPTURING_PHASE,
* AT_TARGET, and BUBBLING_PHASE.
*/
get eventPhase() {
return this._eventPhase;
}
private set eventPhase(value: 0 | 1 | 2 | 3) {
this._eventPhase = value;
}
private _currentTarget: Observable | null = null;
/**
* Returns the object whose event listener's callback is currently being
* invoked.
*/
get currentTarget() {
return this._currentTarget;
}
private set currentTarget(value: Observable | null) {
this._currentTarget = value;
}
private _target: Observable | null = null;
/** Returns the object to which event is dispatched (its target). */
get target() {
return this._target;
}
private set target(value: Observable | null) {
this._target = value;
}
// From CustomEvent rather than Event. Can consider factoring out this
// aspect into DOMCustomEvent.
private readonly detail: unknown | null;
private propagationState: EventPropagationState = EventPropagationState.resume;
constructor(
/**
* Returns the type of event, e.g. "click", "hashchange", or "submit".
*/
public type: string,
options: CustomEventInit = {}
) {
const { bubbles = false, cancelable = false, composed = false, detail = null } = options;
this.bubbles = bubbles;
this.cancelable = cancelable;
this.composed = composed;
this.detail = detail;
}
/**
* Returns the invocation target objects of event's path (objects on which
* listeners will be invoked), except for any nodes in shadow trees of which
* the shadow root's mode is "closed" that are not reachable from event's
* currentTarget.
*/
composedPath(): Observable[] {
if (!this.target) {
return [];
}
// Walk up the target's parents if it has parents (is a ViewBase or
// subclass of ViewBase) or not (is an Observable).
return this.target.isViewBase() ? this.getEventPath(this.target, 'bubble') : [this.target];
}
/**
* Returns the event path by walking up the target's parents.
*
* - 'capture' paths are ordered from root to target.
* - 'bubble' paths are ordered from target to root.
* @example
* [Page, StackLayout, Button] // 'capture'
* @example
* [Button, StackLayout, Page] // 'bubble'
*/
private getEventPath(responder: ViewBase, path: 'capture' | 'bubble'): ViewBase[] {
const chain = [responder];
let nextResponder = responder.parent;
while (nextResponder) {
path === 'capture' ? chain.unshift(nextResponder) : chain.push(nextResponder);
// TODO: decide whether to walk up from Page to Frame, and whether
// to then walk from Frame to Application or something.
nextResponder = nextResponder?.parent;
}
return chain;
}
/** @deprecated */
// eslint-disable-next-line @typescript-eslint/no-unused-vars
initEvent(type: string, bubbles?: boolean, cancelable?: boolean): void {
// This would be trivial to implement, but it's quite nice for `bubbles`
// and `cancelable` to not have backing variables.
throw new Error('Deprecated; use Event() instead.');
}
/**
* If invoked when the cancelable attribute value is true, and while
* executing a listener for the event with passive set to false, signals to
* the operation that caused event to be dispatched that it needs to be
* canceled.
*/
preventDefault(): void {
if (!this.cancelable) {
return;
}
this._canceled = true;
}
/**
* Invoking this method prevents event from reaching any registered event
* listeners after the current one finishes running and, when dispatched in
* a tree, also prevents event from reaching any other objects.
*/
stopImmediatePropagation(): void {
this.propagationState = EventPropagationState.stopImmediate;
}
/**
* When dispatched in a tree, invoking this method prevents event from
* reaching any objects other than the current object.
*/
stopPropagation(): void {
this.propagationState = EventPropagationState.stop;
}
/**
* Dispatches a synthetic event event to target and returns true if either
* event's cancelable attribute value is false or its preventDefault()
* method was not invoked, and false otherwise.
*/
dispatchTo({ target, data, getGlobalEventHandlersPreHandling, getGlobalEventHandlersPostHandling }: { target: Observable; data: EventData; getGlobalEventHandlersPreHandling?: () => readonly ListenerEntry[]; getGlobalEventHandlersPostHandling?: () => readonly ListenerEntry[] }): boolean {
if (this.eventPhase !== this.NONE) {
throw new Error('Tried to dispatch a dispatching event');
}
this.eventPhase = this.CAPTURING_PHASE;
this.target = target;
this._canceled = false;
/**
* Resets any internal state to allow the event to be redispatched. Call
* this before returning.
*/
const reset = () => {
this.currentTarget = null;
this.target = null;
this.eventPhase = this.NONE;
this.propagationState = EventPropagationState.resume;
};
// `Observable.removeEventListener` would likely suffice, but grabbing
// the static method named `removeEventListener` on the target's class
// allows us to be robust to the possiblity of the case of the target
// overriding it (however unlikely).
const removeGlobalEventListener = (target.constructor as unknown as typeof target).removeEventListener.bind(target.constructor) as Observable['removeEventListener'];
// Global event handlers are a NativeScript-only concept, so we'll not
// try to add new formal event phases for them (as that could break DOM
// libraries expecting strictly four phases).
//
// Instead, events handled by global event handlers will exhibit the
// following values:
// - For 'pre-handling phase' global event handlers:
// - eventPhase: CAPTURING_PHASE
// - currentTarget: null
// - For 'post-handling phase' global event handlers:
// - eventPhase: BUBBLING_PHASE
// - currentTarget: The value of currentTarget following the capturing
// and bubbling phases.
// So effectively, we don't make any changes when handling a global
// event. This keeps behaviour as consistent with DOM Events as
// possible.
this.handleEvent({
data,
isGlobal: true,
getListenersForType: () => getGlobalEventHandlersPreHandling?.() ?? emptyArray,
removeEventListener: removeGlobalEventListener,
phase: this.CAPTURING_PHASE,
});
const eventPath = target.isViewBase() ? this.getEventPath(target, 'capture') : [target];
// Capturing phase, e.g. [Page, StackLayout, Button]
for (const currentTarget of eventPath) {
this.currentTarget = currentTarget;
this.eventPhase = this.target === this.currentTarget ? this.AT_TARGET : this.CAPTURING_PHASE;
this.handleEvent({
data,
isGlobal: false,
getListenersForType: () => currentTarget.getEventList(this.type) ?? emptyArray,
removeEventListener: currentTarget.removeEventListener.bind(currentTarget) as Observable['removeEventListener'],
phase: this.CAPTURING_PHASE,
});
if (this.propagationState !== EventPropagationState.resume) {
reset();
return this.returnValue;
}
}
// Bubbling phase, e.g. [Button, StackLayout, Page]
// It's correct to dispatch the event to the target during both phases.
for (const currentTarget of eventPath.reverse()) {
this.currentTarget = currentTarget;
this.eventPhase = this.target === this.currentTarget ? this.AT_TARGET : this.BUBBLING_PHASE;
this.handleEvent({
data,
isGlobal: false,
getListenersForType: () => currentTarget.getEventList(this.type) ?? emptyArray,
removeEventListener: currentTarget.removeEventListener.bind(currentTarget) as Observable['removeEventListener'],
phase: this.BUBBLING_PHASE,
});
if (this.propagationState !== EventPropagationState.resume) {
reset();
return this.returnValue;
}
// If the event doesn't bubble, then, having dispatched it at the
// target (the first iteration of this loop) we don't let it
// propagate any further.
if (!this.bubbles) {
reset();
break;
}
// Restore event phase in case it changed to AT_TARGET during
// this.handleEvent().
this.eventPhase = this.BUBBLING_PHASE;
}
this.handleEvent({
data,
isGlobal: true,
getListenersForType: () => getGlobalEventHandlersPostHandling?.() ?? emptyArray,
removeEventListener: removeGlobalEventListener,
phase: this.BUBBLING_PHASE,
});
reset();
return this.returnValue;
}
private handleEvent({ data, isGlobal, getListenersForType, phase, removeEventListener }: { data: EventData; isGlobal: boolean; getListenersForType: () => readonly ListenerEntry[]; phase: 0 | 1 | 2 | 3; removeEventListener: (eventName: string, callback?: any, thisArg?: any, capture?: boolean) => void }) {
// Work on a copy of the array, as any callback could modify the
// original array during the loop.
const listenersForTypeCopy = getListenersForType().slice();
for (let i = listenersForTypeCopy.length - 1; i >= 0; i--) {
const listener = listenersForTypeCopy[i];
const { callback, capture, thisArg, once, passive } = listener;
// The event listener may have been removed since we took a copy of
// the array, so bail out if so.
//
// We simply use a strict equality check here because we trust that
// the listeners provider will never allow two deeply-equal
// listeners into the array.
if (!getListenersForType().includes(listener)) {
continue;
}
// Handle only the events appropriate to the phase. Global events
// (a NativeScript-only concept) are allowed to be handled
// regardless of phase, for backwards-compatibility.
if (!isGlobal && ((phase === this.CAPTURING_PHASE && !capture) || (phase === this.BUBBLING_PHASE && capture))) {
continue;
}
if (once) {
removeEventListener(this.type, callback, thisArg, capture);
}
// Consistent with the original implementation, we only apply
// context to the function if thisArg is truthy.
const returnValue = callback.apply(thisArg || undefined, [data]);
// This ensures that errors thrown inside asynchronous functions do
// not get swallowed.
if (returnValue instanceof Promise) {
returnValue.catch(console.error);
}
if (passive && event.defaultPrevented) {
console.warn('Unexpected call to event.preventDefault() in passive event listener.');
}
if (this.propagationState === EventPropagationState.stopImmediate) {
return;
}
}
}
}
enum EventPropagationState {
resume,
stop,
stopImmediate,
}

5
packages/core/data/observable-array/index.ts
View File

@@ -428,8 +428,9 @@ export interface ObservableArray<T> {
* @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
* @param callback - Callback function which will be executed when event is raised.
* @param thisArg - An optional parameter which will be used as `this` context for callback execution.
* @param options An optional parameter. If passed as a boolean, configures the useCapture value. Otherwise, specifies options.
*/
on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void;
on(eventNames: string, callback: (data: EventData) => void, thisArg?: any, options?: AddEventListenerOptions | boolean): void;
on(event: 'change', callback: (args: ChangedData<T>) => void, thisArg?: any): void;
on(event: 'change', callback: (args: ChangedData<T>) => void, thisArg?: any, options?: AddEventListenerOptions | boolean): void;
}

83
packages/core/data/observable/index.d.ts vendored
View File

@@ -35,6 +35,11 @@ export interface PropertyChangeData extends EventData {
oldValue?: any;
}
export interface ListenerEntry extends AddEventListenerOptions {
callback: (data: EventData) => void;
thisArg: any;
}
/**
* Helper class that is used to fire property change even when real object is the same.
* By default property change will not be fired for a same object.
@@ -85,42 +90,45 @@ export class Observable {
* @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
* @param callback - Callback function which will be executed when event is raised.
* @param thisArg - An optional parameter which will be used as `this` context for callback execution.
* @param options An optional parameter. If passed as a boolean, configures the useCapture value. Otherwise, specifies options.
*/
on(eventNames: string, callback: (data: EventData) => void, thisArg?: any);
static on(eventName: string, callback: any, thisArg?: any): void;
on(eventNames: string, callback: (data: EventData) => void, thisArg?: any, options?: AddEventListenerOptions | boolean): void;
/**
* Raised when a propertyChange occurs.
*/
on(event: 'propertyChange', callback: (data: EventData) => void, thisArg?: any);
on(event: 'propertyChange', callback: (data: EventData) => void, thisArg?: any, options?: AddEventListenerOptions | boolean): void;
static on(eventName: string, callback: (data: EventData) => void, thisArg?: any, capture?: boolean): void;
/**
* Adds one-time listener function for the event named `event`.
* @param event Name of the event to attach to.
* @param callback A function to be called when the specified event is raised.
* @param thisArg An optional parameter which when set will be used as "this" in callback method call.
* @param options An optional parameter. If passed as a boolean, configures the useCapture value. Otherwise, specifies options.
*/
once(event: string, callback: (data: EventData) => void, thisArg?: any);
once(event: string, callback: (data: EventData) => void, thisArg?: any, options?: AddEventListenerOptions | boolean): void;
static once(eventName: string, callback: any, thisArg?: any): void;
static once(eventName: string, callback: (data: EventData) => void, thisArg?: any, options?: AddEventListenerOptions | boolean): void;
/**
* Shortcut alias to the removeEventListener method.
*/
off(eventNames: string, callback?: any, thisArg?: any);
off(eventNames: string, callback?: (data: EventData) => void, thisArg?: any, options?: EventListenerOptions | boolean): void;
static off(eventName: string, callback?: any, thisArg?: any): void;
static off(eventName: string, callback?: (data: EventData) => void, thisArg?: any, options?: EventListenerOptions | boolean): void;
/**
* Adds a listener for the specified event name.
* @param eventNames Comma delimited names of the events to attach the listener to.
* @param callback A function to be called when some of the specified event(s) is raised.
* @param thisArg An optional parameter which when set will be used as "this" in callback method call.
* @param options An optional parameter. If passed as a boolean, configures the useCapture value. Otherwise, specifies options.
*/
addEventListener(eventNames: string, callback: (data: EventData) => void, thisArg?: any);
addEventListener(eventNames: string, callback: (data: EventData) => void, thisArg?: any, options?: AddEventListenerOptions | boolean): void;
static addEventListener(eventName: string, callback: any, thisArg?: any): void;
static addEventListener(eventName: string, callback: (data: EventData) => void, thisArg?: any, options?: AddEventListenerOptions | boolean): void;
/**
* Removes listener(s) for the specified event name.
@@ -128,9 +136,9 @@ export class Observable {
* @param callback An optional parameter pointing to a specific listener. If not defined, all listeners for the event names will be removed.
* @param thisArg An optional parameter which when set will be used to refine search of the correct callback which will be removed as event listener.
*/
removeEventListener(eventNames: string, callback?: any, thisArg?: any);
removeEventListener(eventNames: string, callback?: (data: EventData) => void, thisArg?: any, options?: EventListenerOptions | boolean): void;
static removeEventListener(eventName: string, callback?: any, thisArg?: any): void;
static removeEventListener(eventName: string, callback?: (data: EventData) => void, thisArg?: any, options?: EventListenerOptions | boolean): void;
/**
* Updates the specified property with the provided value.
@@ -148,10 +156,52 @@ export class Observable {
get(name: string): any;
/**
* Notifies all the registered listeners for the event provided in the data.eventName.
* Notifies all the registered listeners for the event provided in the
* data.eventName.
*
* Old behaviour (for reference):
* - pre-handling phase: Notifies all observers registered globally, i.e.
* for the given event name on the given class name (or all class names)
* with the eventName suffix 'First'.
*
* - handling phase: Notifies all observers registered on the Observable
* itself.
*
* - post-handling phase: Notifies all observers registered globally, i.e.
* for the given event name on the given class name (or all class names)
* without any eventName suffix.
*
*
* New behaviour (based on DOM, but backwards-compatible):
* - pre-handling phase: Same as above.
*
* - capturing phase: Calls the callback for event listeners registered on
* each ancestor of the target in turn (starting with the most ancestral),
* but not the target itself.
*
* - at-target phase: Calls the callback for event listeners registered on
* the target. Equivalent to the old 'handling phase'.
*
* - bubbling phase: Calls the callback for event listeners registered on
* each ancestor of the target (again, not the target itself) in turn,
* starting with the immediate parent.
*
* - post-handling phase: Same as above.
*
* - The progragation can be stopped in any of these phases using
* event.stopPropagation() or event.stopImmediatePropagation().
*
* The old behaviour is the default. That is to say, by taking the default
* option of { bubbles: false } and ensuring that any event listeners added
* also use the default option of { capture: false }, then the event will
* go through just the pre-handling, at-target, and post-handling phases. As
* long as none of the new DOM-specific features like stopPropagation() are
* used, it will behave equivalently.
*
* @param data The data associated with the event.
* @param options Options for the event, in line with DOM Standard.
*/
notify<T extends NotifyData>(data: T): void;
notify<T extends NotifyData>(data: T, options?: CustomEventInit): boolean;
/**
* Notifies all the registered listeners for the property change event.
@@ -177,6 +227,11 @@ export class Observable {
* @private
*/
public _isViewBase: boolean;
/**
* Type predicate to accompany the _isViewBase property.
* @private
*/
public isViewBase(): this is boolean;
//@endprivate
}

314
packages/core/data/observable/index.ts
View File

@@ -1,3 +1,6 @@
import type { ViewBase } from '../../ui/core/view-base';
import { DOMEvent } from '../dom-events/dom-event';
import { Observable as ObservableDefinition, WrappedValue as WrappedValueDefinition } from '.';
export interface EventData {
@@ -20,10 +23,9 @@ export interface PropertyChangeData extends EventData {
oldValue?: any;
}
interface ListenerEntry {
export interface ListenerEntry extends AddEventListenerOptions {
callback: (data: EventData) => void;
thisArg: any;
once?: true;
}
let _wrappedIndex = 0;
@@ -45,13 +47,20 @@ export class WrappedValue implements WrappedValueDefinition {
const _wrappedValues = [new WrappedValue(null), new WrappedValue(null), new WrappedValue(null), new WrappedValue(null), new WrappedValue(null)];
const _globalEventHandlers = {};
const _globalEventHandlers: {
[eventClass: string]: {
[eventName: string]: ListenerEntry[];
};
} = {};
export class Observable implements ObservableDefinition {
public static propertyChangeEvent = 'propertyChange';
public _isViewBase: boolean;
isViewBase(): this is ViewBase {
return this._isViewBase;
}
private _observers = {};
private readonly _observers: { [eventName: string]: ListenerEntry[] } = {};
public get(name: string): any {
return this[name];
@@ -85,28 +94,19 @@ export class Observable implements ObservableDefinition {
}
}
public on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void {
this.addEventListener(eventNames, callback, thisArg);
public on(eventNames: string, callback: (data: EventData) => void, thisArg?: any, options?: AddEventListenerOptions | boolean): void {
this.addEventListener(eventNames, callback, thisArg, options);
}
public once(event: string, callback: (data: EventData) => void, thisArg?: any): void {
if (typeof event !== 'string') {
throw new TypeError('Event must be string.');
}
if (typeof callback !== 'function') {
throw new TypeError('callback must be function.');
}
const list = this._getEventList(event, true);
list.push({ callback, thisArg, once: true });
public once(event: string, callback: (data: EventData) => void, thisArg?: any, options?: (AddEventListenerOptions & { once: true }) | boolean): void {
this.addEventListener(event, callback, thisArg, { ...normalizeEventOptions(options), once: true });
}
public off(eventNames: string, callback?: any, thisArg?: any): void {
this.removeEventListener(eventNames, callback, thisArg);
public off(eventNames: string, callback?: (data: EventData) => void, thisArg?: any, options?: EventListenerOptions | boolean): void {
this.removeEventListener(eventNames, callback, thisArg, options);
}
public addEventListener(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void {
public addEventListener(eventNames: string, callback: (data: EventData) => void, thisArg?: any, options?: AddEventListenerOptions | boolean): void {
if (typeof eventNames !== 'string') {
throw new TypeError('Events name(s) must be string.');
}
@@ -115,76 +115,65 @@ export class Observable implements ObservableDefinition {
throw new TypeError('callback must be function.');
}
const events = eventNames.split(',');
const events = eventNames.trim().split(eventDelimiterPattern);
for (let i = 0, l = events.length; i < l; i++) {
const event = events[i].trim();
const list = this._getEventList(event, true);
const event = events[i];
const list = this.getEventList(event, true);
if (Observable._indexOfListener(list, callback, thisArg, options) >= 0) {
// Don't allow addition of duplicate event listeners.
continue;
}
// TODO: Performance optimization - if we do not have the thisArg specified, do not wrap the callback in additional object (ObserveEntry)
list.push({
callback: callback,
thisArg: thisArg,
callback,
thisArg,
...normalizeEventOptions(options),
});
}
}
public removeEventListener(eventNames: string, callback?: any, thisArg?: any): void {
public removeEventListener(eventNames: string, callback?: (data: EventData) => void, thisArg?: any, options?: EventListenerOptions | boolean): void {
if (typeof eventNames !== 'string') {
throw new TypeError('Events name(s) must be string.');
}
if (callback && typeof callback !== 'function') {
throw new TypeError('callback must be function.');
throw new TypeError('Callback, if provided, must be function.');
}
const events = eventNames.split(',');
for (let i = 0, l = events.length; i < l; i++) {
const event = events[i].trim();
if (callback) {
const list = this._getEventList(event, false);
if (list) {
const index = Observable._indexOfListener(list, callback, thisArg);
if (index >= 0) {
list.splice(index, 1);
}
if (list.length === 0) {
delete this._observers[event];
}
}
} else {
this._observers[event] = undefined;
for (const event of eventNames.trim().split(eventDelimiterPattern)) {
if (!callback) {
delete this._observers[event];
continue;
}
const list = this.getEventList(event, false);
if (list) {
const index = Observable._indexOfListener(list, callback, thisArg, options);
if (index >= 0) {
list.splice(index, 1);
}
if (list.length === 0) {
delete this._observers[event];
}
}
}
}
public static on(eventName: string, callback: any, thisArg?: any): void {
this.addEventListener(eventName, callback, thisArg);
public static on(eventName: string, callback: (data: EventData) => void, thisArg?: any, options?: AddEventListenerOptions | boolean): void {
this.addEventListener(eventName, callback, thisArg, options);
}
public static once(eventName: string, callback: any, thisArg?: any): void {
if (typeof eventName !== 'string') {
throw new TypeError('Event must be string.');
}
if (typeof callback !== 'function') {
throw new TypeError('callback must be function.');
}
const eventClass = this.name === 'Observable' ? '*' : this.name;
if (!_globalEventHandlers[eventClass]) {
_globalEventHandlers[eventClass] = {};
}
if (!Array.isArray(_globalEventHandlers[eventClass][eventName])) {
_globalEventHandlers[eventClass][eventName] = [];
}
_globalEventHandlers[eventClass][eventName].push({ callback, thisArg, once: true });
public static once(eventName: string, callback: (data: EventData) => void, thisArg?: any, options?: (AddEventListenerOptions & { once: true }) | boolean): void {
this.addEventListener(eventName, callback, thisArg, { ...normalizeEventOptions(options), once: true });
}
public static off(eventName: string, callback?: any, thisArg?: any): void {
this.removeEventListener(eventName, callback, thisArg);
public static off(eventName: string, callback?: (data: EventData) => void, thisArg?: any, options?: EventListenerOptions | boolean): void {
this.removeEventListener(eventName, callback, thisArg, options);
}
public static removeEventListener(eventName: string, callback?: any, thisArg?: any): void {
public static removeEventListener(eventName: string, callback?: (data: EventData) => void, thisArg?: any, options?: EventListenerOptions | boolean): void {
if (typeof eventName !== 'string') {
throw new TypeError('Event must be string.');
}
@@ -201,38 +190,29 @@ export class Observable implements ObservableDefinition {
}
const events = _globalEventHandlers[eventClass][eventName];
if (thisArg) {
for (let i = 0; i < events.length; i++) {
if (events[i].callback === callback && events[i].thisArg === thisArg) {
events.splice(i, 1);
i--;
}
}
} else if (callback) {
for (let i = 0; i < events.length; i++) {
if (events[i].callback === callback) {
events.splice(i, 1);
i--;
}
if (callback) {
const index = Observable._indexOfListener(events, callback, thisArg, options);
if (index >= 0) {
events.splice(index, 1);
}
} else {
// Clear all events of this type
delete _globalEventHandlers[eventClass][eventName];
}
if (events.length === 0) {
if (!events.length) {
// Clear all events of this type
delete _globalEventHandlers[eventClass][eventName];
}
// Clear the primary class grouping if no events are left
const keys = Object.keys(_globalEventHandlers[eventClass]);
if (keys.length === 0) {
if (!keys.length) {
delete _globalEventHandlers[eventClass];
}
}
public static addEventListener(eventName: string, callback: any, thisArg?: any): void {
public static addEventListener(eventName: string, callback: (data: EventData) => void, thisArg?: any, options?: AddEventListenerOptions | boolean): void {
if (typeof eventName !== 'string') {
throw new TypeError('Event must be string.');
}
@@ -248,73 +228,90 @@ export class Observable implements ObservableDefinition {
if (!Array.isArray(_globalEventHandlers[eventClass][eventName])) {
_globalEventHandlers[eventClass][eventName] = [];
}
_globalEventHandlers[eventClass][eventName].push({ callback, thisArg });
}
private _globalNotify<T extends EventData>(eventClass: string, eventType: string, data: T): void {
// Check for the Global handlers for JUST this class
if (_globalEventHandlers[eventClass]) {
const event = data.eventName + eventType;
const events = _globalEventHandlers[eventClass][event];
if (events) {
Observable._handleEvent(events, data);
}
}
// Check for he Global handlers for ALL classes
if (_globalEventHandlers['*']) {
const event = data.eventName + eventType;
const events = _globalEventHandlers['*'][event];
if (events) {
Observable._handleEvent(events, data);
}
}
}
public notify<T extends NotifyData>(data: T): void {
const eventData = data as EventData;
eventData.object = eventData.object || this;
const eventClass = this.constructor.name;
this._globalNotify(eventClass, 'First', eventData);
const observers = <Array<ListenerEntry>>this._observers[data.eventName];
if (observers) {
Observable._handleEvent(observers, eventData);
}
this._globalNotify(eventClass, '', eventData);
}
private static _handleEvent<T extends EventData>(observers: Array<ListenerEntry>, data: T): void {
if (!observers) {
const list = _globalEventHandlers[eventClass][eventName];
if (Observable._indexOfListener(list, callback, thisArg, options) >= 0) {
// Don't allow addition of duplicate event listeners.
return;
}
for (let i = observers.length - 1; i >= 0; i--) {
const entry = observers[i];
if (entry) {
if (entry.once) {
observers.splice(i, 1);
}
let returnValue;
if (entry.thisArg) {
returnValue = entry.callback.apply(entry.thisArg, [data]);
} else {
returnValue = entry.callback(data);
}
// This ensures errors thrown inside asynchronous functions do not get swallowed
if (returnValue && returnValue instanceof Promise) {
returnValue.catch((err) => {
console.error(err);
});
}
}
}
_globalEventHandlers[eventClass][eventName].push({
callback,
thisArg,
...normalizeEventOptions(options),
});
}
public notifyPropertyChange(name: string, value: any, oldValue?: any) {
this.notify(this._createPropertyChangeData(name, value, oldValue));
/**
* Notifies all the registered listeners for the event provided in the
* data.eventName.
*
* Old behaviour (for reference):
* - pre-handling phase: Notifies all observers registered globally, i.e.
* for the given event name on the given class name (or all class names)
* with the eventName suffix 'First'.
*
* - handling phase: Notifies all observers registered on the Observable
* itself.
*
* - post-handling phase: Notifies all observers registered globally, i.e.
* for the given event name on the given class name (or all class names)
* without any eventName suffix.
*
*
* New behaviour (based on DOM, but backwards-compatible):
* - pre-handling phase: Same as above.
*
* - capturing phase: Calls the callback for event listeners registered on
* each ancestor of the target in turn (starting with the most ancestral),
* but not the target itself.
*
* - at-target phase: Calls the callback for event listeners registered on
* the target. Equivalent to the old 'handling phase'.
*
* - bubbling phase: Calls the callback for event listeners registered on
* each ancestor of the target (again, not the target itself) in turn,
* starting with the immediate parent.
*
* - post-handling phase: Same as above.
*
* - The progragation can be stopped in any of these phases using
* event.stopPropagation() or event.stopImmediatePropagation().
*
* The old behaviour is the default. That is to say, by taking the default
* option of { bubbles: false } and ensuring that any event listeners added
* also use the default option of { capture: false }, then the event will
* go through just the pre-handling, at-target, and post-handling phases. As
* long as none of the new DOM-specific features like stopPropagation() are
* used, it will behave equivalently.
*
* @param data The data associated with the event.
* @param options Options for the event, in line with DOM Standard.
*/
public notify<T extends NotifyData>(data: T, options?: CustomEventInit): void {
data.object = data.object || this;
// Now that we've filled in the `object` field (that was optional in
// NotifyData), `data` can be treated as EventData.
const eventData = data as EventData;
new DOMEvent(data.eventName, options).dispatchTo({
target: this,
data: eventData,
getGlobalEventHandlersPreHandling: () => this._getGlobalEventHandlers(eventData, 'First'),
getGlobalEventHandlersPostHandling: () => this._getGlobalEventHandlers(eventData, ''),
});
}
private _getGlobalEventHandlers(data: EventData, eventType: 'First' | ''): ListenerEntry[] {
const eventClass = data.object?.constructor?.name;
const globalEventHandlersForOwnClass = _globalEventHandlers[eventClass]?.[`${data.eventName}${eventType}`] ?? [];
const globalEventHandlersForAllClasses = _globalEventHandlers['*']?.[`${data.eventName}${eventType}`] ?? [];
return [...globalEventHandlersForOwnClass, ...globalEventHandlersForAllClasses];
}
public notifyPropertyChange(name: string, value: any, oldValue?: any, options?: CustomEventInit) {
this.notify(this._createPropertyChangeData(name, value, oldValue), options);
}
public hasListeners(eventName: string) {
@@ -332,20 +329,17 @@ export class Observable implements ObservableDefinition {
}
public _emit(eventNames: string) {
const events = eventNames.split(',');
for (let i = 0, l = events.length; i < l; i++) {
const event = events[i].trim();
for (const event of eventNames.trim().split(eventDelimiterPattern)) {
this.notify({ eventName: event, object: this });
}
}
private _getEventList(eventName: string, createIfNeeded?: boolean): Array<ListenerEntry> {
public getEventList(eventName: string, createIfNeeded?: boolean): ListenerEntry[] | undefined {
if (!eventName) {
throw new TypeError('EventName must be valid string.');
}
let list = <Array<ListenerEntry>>this._observers[eventName];
let list = this._observers[eventName];
if (!list && createIfNeeded) {
list = [];
this._observers[eventName] = list;
@@ -354,21 +348,9 @@ export class Observable implements ObservableDefinition {
return list;
}
private static _indexOfListener(list: Array<ListenerEntry>, callback: (data: EventData) => void, thisArg?: any): number {
for (let i = 0; i < list.length; i++) {
const entry = list[i];
if (thisArg) {
if (entry.callback === callback && entry.thisArg === thisArg) {
return i;
}
} else {
if (entry.callback === callback) {
return i;
}
}
}
return -1;
protected static _indexOfListener(list: Array<ListenerEntry>, callback: (data: EventData) => void, thisArg?: any, options?: EventListenerOptions | boolean): number {
const capture = normalizeEventOptions(options)?.capture ?? false;
return list.findIndex((entry) => entry.callback === callback && (!thisArg || entry.thisArg === thisArg) && !!entry.capture === capture);
}
}
@@ -416,6 +398,12 @@ function addPropertiesFromObject(observable: ObservableFromObject, source: any,
});
}
export const eventDelimiterPattern = /\s*,\s*/;
export function normalizeEventOptions(options?: AddEventListenerOptions | boolean) {
return typeof options === 'object' ? options : { capture: options };
}
export function fromObject(source: any): Observable {
const observable = new ObservableFromObject();
addPropertiesFromObject(observable, source, false);