@ckeditor/ckeditor5-utils 35.0.0 → 35.0.1

package/src/emittermixin.js

@@ -0,0 +1,471 @@
+/**
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module utils/emittermixin
+ */
+import EventInfo from './eventinfo';
+import uid from './uid';
+import priorities from './priorities';
+import insertToPriorityArray from './inserttopriorityarray';
+// To check if component is loaded more than once.
+import './version';
+import CKEditorError from './ckeditorerror';
+const _listeningTo = Symbol('listeningTo');
+const _emitterId = Symbol('emitterId');
+const _delegations = Symbol('delegations');
+/**
+ * Mixin that injects the {@link ~Emitter events API} into its host.
+ *
+ * Read more about the concept of emitters in the:
+ * * {@glink framework/guides/architecture/core-editor-architecture#event-system-and-observables Event system and observables}
+ * section of the {@glink framework/guides/architecture/core-editor-architecture Core editor architecture} guide.
+ * * {@glink framework/guides/deep-dive/event-system Event system} deep dive guide.
+ *
+ * @mixin EmitterMixin
+ * @implements module:utils/emittermixin~Emitter
+ */
+const EmitterMixin = {
+    /**
+     * @inheritDoc
+     */
+    on(event, callback, options = {}) {
+        this.listenTo(this, event, callback, options);
+    },
+    /**
+     * @inheritDoc
+     */
+    once(event, callback, options) {
+        let wasFired = false;
+        const onceCallback = (event, ...args) => {
+            // Ensure the callback is called only once even if the callback itself leads to re-firing the event
+            // (which would call the callback again).
+            if (!wasFired) {
+                wasFired = true;
+                // Go off() at the first call.
+                event.off();
+                // Go with the original callback.
+                callback.call(this, event, ...args);
+            }
+        };
+        // Make a similar on() call, simply replacing the callback.
+        this.listenTo(this, event, onceCallback, options);
+    },
+    /**
+     * @inheritDoc
+     */
+    off(event, callback) {
+        this.stopListening(this, event, callback);
+    },
+    /**
+     * @inheritDoc
+     */
+    listenTo(emitter, event, callback, options = {}) {
+        let emitterInfo, eventCallbacks;
+        // _listeningTo contains a list of emitters that this object is listening to.
+        // This list has the following format:
+        //
+        // _listeningTo: {
+        //     emitterId: {
+        //         emitter: emitter,
+        //         callbacks: {
+        //             event1: [ callback1, callback2, ... ]
+        //             ....
+        //         }
+        //     },
+        //     ...
+        // }
+        if (!this[_listeningTo]) {
+            this[_listeningTo] = {};
+        }
+        const emitters = this[_listeningTo];
+        if (!_getEmitterId(emitter)) {
+            _setEmitterId(emitter);
+        }
+        const emitterId = _getEmitterId(emitter);
+        if (!(emitterInfo = emitters[emitterId])) {
+            emitterInfo = emitters[emitterId] = {
+                emitter,
+                callbacks: {}
+            };
+        }
+        if (!(eventCallbacks = emitterInfo.callbacks[event])) {
+            eventCallbacks = emitterInfo.callbacks[event] = [];
+        }
+        eventCallbacks.push(callback);
+        // Finally register the callback to the event.
+        addEventListener(this, emitter, event, callback, options);
+    },
+    /**
+     * @inheritDoc
+     */
+    stopListening(emitter, event, callback) {
+        const emitters = this[_listeningTo];
+        let emitterId = emitter && _getEmitterId(emitter);
+        const emitterInfo = (emitters && emitterId) ? emitters[emitterId] : undefined;
+        const eventCallbacks = (emitterInfo && event) ? emitterInfo.callbacks[event] : undefined;
+        // Stop if nothing has been listened.
+        if (!emitters || (emitter && !emitterInfo) || (event && !eventCallbacks)) {
+            return;
+        }
+        // All params provided. off() that single callback.
+        if (callback) {
+            removeEventListener(this, emitter, event, callback);
+            // We must remove callbacks as well in order to prevent memory leaks.
+            // See https://github.com/ckeditor/ckeditor5/pull/8480
+            const index = eventCallbacks.indexOf(callback);
+            if (index !== -1) {
+                if (eventCallbacks.length === 1) {
+                    delete emitterInfo.callbacks[event];
+                }
+                else {
+                    removeEventListener(this, emitter, event, callback);
+                }
+            }
+        }
+        // Only `emitter` and `event` provided. off() all callbacks for that event.
+        else if (eventCallbacks) {
+            while ((callback = eventCallbacks.pop())) {
+                removeEventListener(this, emitter, event, callback);
+            }
+            delete emitterInfo.callbacks[event];
+        }
+        // Only `emitter` provided. off() all events for that emitter.
+        else if (emitterInfo) {
+            for (event in emitterInfo.callbacks) {
+                this.stopListening(emitter, event);
+            }
+            delete emitters[emitterId];
+        }
+        // No params provided. off() all emitters.
+        else {
+            for (emitterId in emitters) {
+                this.stopListening(emitters[emitterId].emitter);
+            }
+            delete this[_listeningTo];
+        }
+    },
+    /**
+     * @inheritDoc
+     */
+    fire(eventOrInfo, ...args) {
+        try {
+            const eventInfo = eventOrInfo instanceof EventInfo ? eventOrInfo : new EventInfo(this, eventOrInfo);
+            const event = eventInfo.name;
+            let callbacks = getCallbacksForEvent(this, event);
+            // Record that the event passed this emitter on its path.
+            eventInfo.path.push(this);
+            // Handle event listener callbacks first.
+            if (callbacks) {
+                // Arguments passed to each callback.
+                const callbackArgs = [eventInfo, ...args];
+                // Copying callbacks array is the easiest and most secure way of preventing infinite loops, when event callbacks
+                // are added while processing other callbacks. Previous solution involved adding counters (unique ids) but
+                // failed if callbacks were added to the queue before currently processed callback.
+                // If this proves to be too inefficient, another method is to change `.on()` so callbacks are stored if same
+                // event is currently processed. Then, `.fire()` at the end, would have to add all stored events.
+                callbacks = Array.from(callbacks);
+                for (let i = 0; i < callbacks.length; i++) {
+                    callbacks[i].callback.apply(this, callbackArgs);
+                    // Remove the callback from future requests if off() has been called.
+                    if (eventInfo.off.called) {
+                        // Remove the called mark for the next calls.
+                        delete eventInfo.off.called;
+                        this._removeEventListener(event, callbacks[i].callback);
+                    }
+                    // Do not execute next callbacks if stop() was called.
+                    if (eventInfo.stop.called) {
+                        break;
+                    }
+                }
+            }
+            // Delegate event to other emitters if needed.
+            const delegations = this[_delegations];
+            if (delegations) {
+                const destinations = delegations.get(event);
+                const passAllDestinations = delegations.get('*');
+                if (destinations) {
+                    fireDelegatedEvents(destinations, eventInfo, args);
+                }
+                if (passAllDestinations) {
+                    fireDelegatedEvents(passAllDestinations, eventInfo, args);
+                }
+            }
+            return eventInfo.return;
+        }
+        catch (err) {
+            // @if CK_DEBUG // throw err;
+            /* istanbul ignore next */
+            CKEditorError.rethrowUnexpectedError(err, this);
+        }
+    },
+    /**
+     * @inheritDoc
+     */
+    delegate(...events) {
+        return {
+            to: (emitter, nameOrFunction) => {
+                if (!this[_delegations]) {
+                    this[_delegations] = new Map();
+                }
+                // Originally there was a for..of loop which unfortunately caused an error in Babel that didn't allow
+                // build an application. See: https://github.com/ckeditor/ckeditor5-react/issues/40.
+                events.forEach(eventName => {
+                    const destinations = this[_delegations].get(eventName);
+                    if (!destinations) {
+                        this[_delegations].set(eventName, new Map([[emitter, nameOrFunction]]));
+                    }
+                    else {
+                        destinations.set(emitter, nameOrFunction);
+                    }
+                });
+            }
+        };
+    },
+    /**
+     * @inheritDoc
+     */
+    stopDelegating(event, emitter) {
+        if (!this[_delegations]) {
+            return;
+        }
+        if (!event) {
+            this[_delegations].clear();
+        }
+        else if (!emitter) {
+            this[_delegations].delete(event);
+        }
+        else {
+            const destinations = this[_delegations].get(event);
+            if (destinations) {
+                destinations.delete(emitter);
+            }
+        }
+    },
+    /**
+     * @inheritDoc
+     */
+    _addEventListener(event, callback, options) {
+        createEventNamespace(this, event);
+        const lists = getCallbacksListsForNamespace(this, event);
+        const priority = priorities.get(options.priority);
+        const callbackDefinition = {
+            callback,
+            priority
+        };
+        // Add the callback to all callbacks list.
+        for (const callbacks of lists) {
+            // Add the callback to the list in the right priority position.
+            insertToPriorityArray(callbacks, callbackDefinition);
+        }
+    },
+    /**
+     * @inheritDoc
+     */
+    _removeEventListener(event, callback) {
+        const lists = getCallbacksListsForNamespace(this, event);
+        for (const callbacks of lists) {
+            for (let i = 0; i < callbacks.length; i++) {
+                if (callbacks[i].callback == callback) {
+                    // Remove the callback from the list (fixing the next index).
+                    callbacks.splice(i, 1);
+                    i--;
+                }
+            }
+        }
+    }
+};
+export default EmitterMixin;
+/**
+ * Checks if `listeningEmitter` listens to an emitter with given `listenedToEmitterId` and if so, returns that emitter.
+ * If not, returns `null`.
+ *
+ * @internal
+ * @protected
+ * @param {module:utils/emittermixin~Emitter} listeningEmitter An emitter that listens.
+ * @param {String} listenedToEmitterId Unique emitter id of emitter listened to.
+ * @returns {module:utils/emittermixin~Emitter|null}
+ */
+export function _getEmitterListenedTo(listeningEmitter, listenedToEmitterId) {
+    const listeningTo = listeningEmitter[_listeningTo];
+    if (listeningTo && listeningTo[listenedToEmitterId]) {
+        return listeningTo[listenedToEmitterId].emitter;
+    }
+    return null;
+}
+/**
+ * Sets emitter's unique id.
+ *
+ * **Note:** `_emitterId` can be set only once.
+ *
+ * @internal
+ * @protected
+ * @param {module:utils/emittermixin~Emitter} emitter An emitter for which id will be set.
+ * @param {String} [id] Unique id to set. If not passed, random unique id will be set.
+ */
+export function _setEmitterId(emitter, id) {
+    if (!emitter[_emitterId]) {
+        emitter[_emitterId] = id || uid();
+    }
+}
+/**
+ * Returns emitter's unique id.
+ *
+ * @internal
+ * @protected
+ * @param {module:utils/emittermixin~Emitter} emitter An emitter which id will be returned.
+ * @returns {String|undefined}
+ */
+export function _getEmitterId(emitter) {
+    return emitter[_emitterId];
+}
+// Gets the internal `_events` property of the given object.
+// `_events` property store all lists with callbacks for registered event names.
+// If there were no events registered on the object, empty `_events` object is created.
+function getEvents(source) {
+    if (!source._events) {
+        Object.defineProperty(source, '_events', {
+            value: {}
+        });
+    }
+    return source._events;
+}
+// Creates event node for generic-specific events relation architecture.
+function makeEventNode() {
+    return {
+        callbacks: [],
+        childEvents: []
+    };
+}
+// Creates an architecture for generic-specific events relation.
+// If needed, creates all events for given eventName, i.e. if the first registered event
+// is foo:bar:abc, it will create foo:bar:abc, foo:bar and foo event and tie them together.
+// It also copies callbacks from more generic events to more specific events when
+// specific events are created.
+function createEventNamespace(source, eventName) {
+    const events = getEvents(source);
+    // First, check if the event we want to add to the structure already exists.
+    if (events[eventName]) {
+        // If it exists, we don't have to do anything.
+        return;
+    }
+    // In other case, we have to create the structure for the event.
+    // Note, that we might need to create intermediate events too.
+    // I.e. if foo:bar:abc is being registered and we only have foo in the structure,
+    // we need to also register foo:bar.
+    // Currently processed event name.
+    let name = eventName;
+    // Name of the event that is a child event for currently processed event.
+    let childEventName = null;
+    // Array containing all newly created specific events.
+    const newEventNodes = [];
+    // While loop can't check for ':' index because we have to handle generic events too.
+    // In each loop, we truncate event name, going from the most specific name to the generic one.
+    // I.e. foo:bar:abc -> foo:bar -> foo.
+    while (name !== '') {
+        if (events[name]) {
+            // If the currently processed event name is already registered, we can be sure
+            // that it already has all the structure created, so we can break the loop here
+            // as no more events need to be registered.
+            break;
+        }
+        // If this event is not yet registered, create a new object for it.
+        events[name] = makeEventNode();
+        // Add it to the array with newly created events.
+        newEventNodes.push(events[name]);
+        // Add previously processed event name as a child of this event.
+        if (childEventName) {
+            events[name].childEvents.push(childEventName);
+        }
+        childEventName = name;
+        // If `.lastIndexOf()` returns -1, `.substr()` will return '' which will break the loop.
+        name = name.substr(0, name.lastIndexOf(':'));
+    }
+    if (name !== '') {
+        // If name is not empty, we found an already registered event that was a parent of the
+        // event we wanted to register.
+        // Copy that event's callbacks to newly registered events.
+        for (const node of newEventNodes) {
+            node.callbacks = events[name].callbacks.slice();
+        }
+        // Add last newly created event to the already registered event.
+        events[name].childEvents.push(childEventName);
+    }
+}
+// Gets an array containing callbacks list for a given event and it's more specific events.
+// I.e. if given event is foo:bar and there is also foo:bar:abc event registered, this will
+// return callback list of foo:bar and foo:bar:abc (but not foo).
+function getCallbacksListsForNamespace(source, eventName) {
+    const eventNode = getEvents(source)[eventName];
+    if (!eventNode) {
+        return [];
+    }
+    let callbacksLists = [eventNode.callbacks];
+    for (let i = 0; i < eventNode.childEvents.length; i++) {
+        const childCallbacksLists = getCallbacksListsForNamespace(source, eventNode.childEvents[i]);
+        callbacksLists = callbacksLists.concat(childCallbacksLists);
+    }
+    return callbacksLists;
+}
+// Get the list of callbacks for a given event, but only if there any callbacks have been registered.
+// If there are no callbacks registered for given event, it checks if this is a specific event and looks
+// for callbacks for it's more generic version.
+function getCallbacksForEvent(source, eventName) {
+    let event;
+    if (!source._events || !(event = source._events[eventName]) || !event.callbacks.length) {
+        // There are no callbacks registered for specified eventName.
+        // But this could be a specific-type event that is in a namespace.
+        if (eventName.indexOf(':') > -1) {
+            // If the eventName is specific, try to find callback lists for more generic event.
+            return getCallbacksForEvent(source, eventName.substr(0, eventName.lastIndexOf(':')));
+        }
+        else {
+            // If this is a top-level generic event, return null;
+            return null;
+        }
+    }
+    return event.callbacks;
+}
+// Fires delegated events for given map of destinations.
+//
+// @private
+// * @param {Map.<utils.Emitter>} destinations A map containing
+// `[ {@link module:utils/emittermixin~Emitter}, "event name" ]` pair destinations.
+// * @param {utils.EventInfo} eventInfo The original event info object.
+// * @param {Array.<*>} fireArgs Arguments the original event was fired with.
+function fireDelegatedEvents(destinations, eventInfo, fireArgs) {
+    for (let [emitter, name] of destinations) {
+        if (!name) {
+            name = eventInfo.name;
+        }
+        else if (typeof name == 'function') {
+            name = name(eventInfo.name);
+        }
+        const delegatedInfo = new EventInfo(eventInfo.source, name);
+        delegatedInfo.path = [...eventInfo.path];
+        emitter.fire(delegatedInfo, ...fireArgs);
+    }
+}
+// Helper for registering event callback on the emitter.
+function addEventListener(listener, emitter, event, callback, options) {
+    if (emitter._addEventListener) {
+        emitter._addEventListener(event, callback, options);
+    }
+    else {
+        // Allow listening on objects that do not implement Emitter interface.
+        // This is needed in some tests that are using mocks instead of the real objects with EmitterMixin mixed.
+        listener._addEventListener.call(emitter, event, callback, options);
+    }
+}
+// Helper for removing event callback from the emitter.
+function removeEventListener(listener, emitter, event, callback) {
+    if (emitter._removeEventListener) {
+        emitter._removeEventListener(event, callback);
+    }
+    else {
+        // Allow listening on objects that do not implement Emitter interface.
+        // This is needed in some tests that are using mocks instead of the real objects with EmitterMixin mixed.
+        listener._removeEventListener.call(emitter, event, callback);
+    }
+}

package/src/env.js

@@ -0,0 +1,168 @@
+/**
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/* globals navigator:false */
+/**
+ * @module utils/env
+ */
+const userAgent = navigator.userAgent.toLowerCase();
+/**
+ * A namespace containing environment and browser information.
+ *
+ * @namespace
+ */
+const env = {
+    /**
+     * Indicates that the application is running on Macintosh.
+     *
+     * @static
+     * @type {Boolean}
+     */
+    isMac: isMac(userAgent),
+    /**
+     * Indicates that the application is running on Windows.
+     *
+     * @static
+     * @type {Boolean}
+     */
+    isWindows: isWindows(userAgent),
+    /**
+     * Indicates that the application is running in Firefox (Gecko).
+     *
+     * @static
+     * @type {Boolean}
+     */
+    isGecko: isGecko(userAgent),
+    /**
+     * Indicates that the application is running in Safari.
+     *
+     * @static
+     * @type {Boolean}
+     */
+    isSafari: isSafari(userAgent),
+    /**
+     * Indicates the the application is running in iOS.
+     *
+     * @static
+     * @type {Boolean}
+     */
+    isiOS: isiOS(userAgent),
+    /**
+     * Indicates that the application is running on Android mobile device.
+     *
+     * @static
+     * @type {Boolean}
+     */
+    isAndroid: isAndroid(userAgent),
+    /**
+     * Indicates that the application is running in a browser using the Blink engine.
+     *
+     * @static
+     * @type {Boolean}
+     */
+    isBlink: isBlink(userAgent),
+    /**
+     * Environment features information.
+     *
+     * @memberOf module:utils/env~env
+     * @namespace
+     */
+    features: {
+        /**
+         * Indicates that the environment supports ES2018 Unicode property escapes — like `\p{P}` or `\p{L}`.
+         * More information about unicode properties might be found
+         * [in Unicode Standard Annex #44](https://www.unicode.org/reports/tr44/#GC_Values_Table).
+         *
+         * @type {Boolean}
+         */
+        isRegExpUnicodePropertySupported: isRegExpUnicodePropertySupported()
+    }
+};
+export default env;
+/**
+ * Checks if User Agent represented by the string is running on Macintosh.
+ *
+ * @param {String} userAgent **Lowercase** `navigator.userAgent` string.
+ * @returns {Boolean} Whether User Agent is running on Macintosh or not.
+ */
+export function isMac(userAgent) {
+    return userAgent.indexOf('macintosh') > -1;
+}
+/**
+ * Checks if User Agent represented by the string is running on Windows.
+ *
+ * @param {String} userAgent **Lowercase** `navigator.userAgent` string.
+ * @returns {Boolean} Whether User Agent is running on Windows or not.
+ */
+export function isWindows(userAgent) {
+    return userAgent.indexOf('windows') > -1;
+}
+/**
+ * Checks if User Agent represented by the string is Firefox (Gecko).
+ *
+ * @param {String} userAgent **Lowercase** `navigator.userAgent` string.
+ * @returns {Boolean} Whether User Agent is Firefox or not.
+ */
+export function isGecko(userAgent) {
+    return !!userAgent.match(/gecko\/\d+/);
+}
+/**
+ * Checks if User Agent represented by the string is Safari.
+ *
+ * @param {String} userAgent **Lowercase** `navigator.userAgent` string.
+ * @returns {Boolean} Whether User Agent is Safari or not.
+ */
+export function isSafari(userAgent) {
+    return userAgent.indexOf(' applewebkit/') > -1 && userAgent.indexOf('chrome') === -1;
+}
+/**
+ * Checks if User Agent represented by the string is running in iOS.
+ *
+ * @param {String} userAgent **Lowercase** `navigator.userAgent` string.
+ * @returns {Boolean} Whether User Agent is running in iOS or not.
+ */
+export function isiOS(userAgent) {
+    // "Request mobile site" || "Request desktop site".
+    return !!userAgent.match(/iphone|ipad/i) || (isMac(userAgent) && navigator.maxTouchPoints > 0);
+}
+/**
+ * Checks if User Agent represented by the string is Android mobile device.
+ *
+ * @param {String} userAgent **Lowercase** `navigator.userAgent` string.
+ * @returns {Boolean} Whether User Agent is Safari or not.
+ */
+export function isAndroid(userAgent) {
+    return userAgent.indexOf('android') > -1;
+}
+/**
+ * Checks if User Agent represented by the string is Blink engine.
+ *
+ * @param {String} userAgent **Lowercase** `navigator.userAgent` string.
+ * @returns {Boolean} Whether User Agent is Blink engine or not.
+ */
+export function isBlink(userAgent) {
+    // The Edge browser before switching to the Blink engine used to report itself as Chrome (and "Edge/")
+    // but after switching to the Blink it replaced "Edge/" with "Edg/".
+    return userAgent.indexOf('chrome/') > -1 && userAgent.indexOf('edge/') < 0;
+}
+/**
+ * Checks if the current environment supports ES2018 Unicode properties like `\p{P}` or `\p{L}`.
+ * More information about unicode properties might be found
+ * [in Unicode Standard Annex #44](https://www.unicode.org/reports/tr44/#GC_Values_Table).
+ *
+ * @returns {Boolean}
+ */
+export function isRegExpUnicodePropertySupported() {
+    let isSupported = false;
+    // Feature detection for Unicode properties. Added in ES2018. Currently Firefox does not support it.
+    // See https://github.com/ckeditor/ckeditor5-mention/issues/44#issuecomment-487002174.
+    try {
+        // Usage of regular expression literal cause error during build (ckeditor/ckeditor5-dev#534).
+        isSupported = 'ć'.search(new RegExp('[\\p{L}]', 'u')) === 0;
+    }
+    catch (error) {
+        // Firefox throws a SyntaxError when the group is unsupported.
+    }
+    return isSupported;
+}

package/src/eventinfo.js

@@ -0,0 +1,26 @@
+/**
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module utils/eventinfo
+ */
+import spy from './spy';
+/**
+ * The event object passed to event callbacks. It is used to provide information about the event as well as a tool to
+ * manipulate it.
+ */
+export default class EventInfo {
+    /**
+     * @param {Object} source The emitter.
+     * @param {String} name The event name.
+     */
+    constructor(source, name) {
+        this.source = source;
+        this.name = name;
+        this.path = [];
+        // The following methods are defined in the constructor because they must be re-created per instance.
+        this.stop = spy();
+        this.off = spy();
+    }
+}