@ckeditor/ckeditor5-engine 39.0.1 → 40.0.0

package/src/view/observer/observer.js

@@ -1,84 +1,84 @@
-/**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-/**
- * @module engine/view/observer/observer
- */
-import { DomEmitterMixin } from '@ckeditor/ckeditor5-utils';
-/**
- * Abstract base observer class. Observers are classes which listen to DOM events, do the preliminary
- * processing and fire events on the {@link module:engine/view/document~Document} objects.
- * Observers can also add features to the view, for instance by updating its status or marking elements
- * which need a refresh on DOM events.
- */
-export default class Observer extends DomEmitterMixin() {
-    /**
-     * Creates an instance of the observer.
-     */
-    constructor(view) {
-        super();
-        /**
-         * The state of the observer. If it is disabled, no events will be fired.
-         */
-        this._isEnabled = false;
-        this.view = view;
-        this.document = view.document;
-    }
-    /**
-     * The state of the observer. If it is disabled, no events will be fired.
-     */
-    get isEnabled() {
-        return this._isEnabled;
-    }
-    /**
-     * Enables the observer. This method is called when the observer is registered to the
-     * {@link module:engine/view/view~View} and after {@link module:engine/view/view~View#forceRender rendering}
-     * (all observers are {@link #disable disabled} before rendering).
-     *
-     * A typical use case for disabling observers is that mutation observers need to be disabled for the rendering.
-     * However, a child class may not need to be disabled, so it can implement an empty method.
-     *
-     * @see module:engine/view/observer/observer~Observer#disable
-     */
-    enable() {
-        this._isEnabled = true;
-    }
-    /**
-     * Disables the observer. This method is called before
-     * {@link module:engine/view/view~View#forceRender rendering} to prevent firing events during rendering.
-     *
-     * @see module:engine/view/observer/observer~Observer#enable
-     */
-    disable() {
-        this._isEnabled = false;
-    }
-    /**
-     * Disables and destroys the observer, among others removes event listeners created by the observer.
-     */
-    destroy() {
-        this.disable();
-        this.stopListening();
-    }
-    /**
-     * Checks whether a given DOM event should be ignored (should not be turned into a synthetic view document event).
-     *
-     * Currently, an event will be ignored only if its target or any of its ancestors has the `data-cke-ignore-events` attribute.
-     * This attribute can be used inside the structures generated by
-     * {@link module:engine/view/downcastwriter~DowncastWriter#createUIElement `DowncastWriter#createUIElement()`} to ignore events
-     * fired within a UI that should be excluded from CKEditor 5's realms.
-     *
-     * @param domTarget The DOM event target to check (usually an element, sometimes a text node and
-     * potentially sometimes a document, too).
-     * @returns Whether this event should be ignored by the observer.
-     */
-    checkShouldIgnoreEventFromTarget(domTarget) {
-        if (domTarget && domTarget.nodeType === 3) {
-            domTarget = domTarget.parentNode;
-        }
-        if (!domTarget || domTarget.nodeType !== 1) {
-            return false;
-        }
-        return domTarget.matches('[data-cke-ignore-events], [data-cke-ignore-events] *');
-    }
-}
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module engine/view/observer/observer
+ */
+import { DomEmitterMixin } from '@ckeditor/ckeditor5-utils';
+/**
+ * Abstract base observer class. Observers are classes which listen to DOM events, do the preliminary
+ * processing and fire events on the {@link module:engine/view/document~Document} objects.
+ * Observers can also add features to the view, for instance by updating its status or marking elements
+ * which need a refresh on DOM events.
+ */
+export default class Observer extends DomEmitterMixin() {
+    /**
+     * Creates an instance of the observer.
+     */
+    constructor(view) {
+        super();
+        /**
+         * The state of the observer. If it is disabled, no events will be fired.
+         */
+        this._isEnabled = false;
+        this.view = view;
+        this.document = view.document;
+    }
+    /**
+     * The state of the observer. If it is disabled, no events will be fired.
+     */
+    get isEnabled() {
+        return this._isEnabled;
+    }
+    /**
+     * Enables the observer. This method is called when the observer is registered to the
+     * {@link module:engine/view/view~View} and after {@link module:engine/view/view~View#forceRender rendering}
+     * (all observers are {@link #disable disabled} before rendering).
+     *
+     * A typical use case for disabling observers is that mutation observers need to be disabled for the rendering.
+     * However, a child class may not need to be disabled, so it can implement an empty method.
+     *
+     * @see module:engine/view/observer/observer~Observer#disable
+     */
+    enable() {
+        this._isEnabled = true;
+    }
+    /**
+     * Disables the observer. This method is called before
+     * {@link module:engine/view/view~View#forceRender rendering} to prevent firing events during rendering.
+     *
+     * @see module:engine/view/observer/observer~Observer#enable
+     */
+    disable() {
+        this._isEnabled = false;
+    }
+    /**
+     * Disables and destroys the observer, among others removes event listeners created by the observer.
+     */
+    destroy() {
+        this.disable();
+        this.stopListening();
+    }
+    /**
+     * Checks whether a given DOM event should be ignored (should not be turned into a synthetic view document event).
+     *
+     * Currently, an event will be ignored only if its target or any of its ancestors has the `data-cke-ignore-events` attribute.
+     * This attribute can be used inside the structures generated by
+     * {@link module:engine/view/downcastwriter~DowncastWriter#createUIElement `DowncastWriter#createUIElement()`} to ignore events
+     * fired within a UI that should be excluded from CKEditor 5's realms.
+     *
+     * @param domTarget The DOM event target to check (usually an element, sometimes a text node and
+     * potentially sometimes a document, too).
+     * @returns Whether this event should be ignored by the observer.
+     */
+    checkShouldIgnoreEventFromTarget(domTarget) {
+        if (domTarget && domTarget.nodeType === 3) {
+            domTarget = domTarget.parentNode;
+        }
+        if (!domTarget || domTarget.nodeType !== 1) {
+            return false;
+        }
+        return domTarget.matches('[data-cke-ignore-events], [data-cke-ignore-events] *');
+    }
+}

package/src/view/observer/selectionobserver.d.ts

@@ -1,148 +1,148 @@
-/**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-/**
- * @module engine/view/observer/selectionobserver
- */
-import Observer from './observer';
-import MutationObserver from './mutationobserver';
-import type View from '../view';
-import type DocumentSelection from '../documentselection';
-import type DomConverter from '../domconverter';
-import type Selection from '../selection';
-import FocusObserver from './focusobserver';
-type DomSelection = globalThis.Selection;
-/**
- * Selection observer class observes selection changes in the document. If a selection changes on the document this
- * observer checks if the DOM selection is different from the {@link module:engine/view/document~Document#selection view selection}.
- * The selection observer fires {@link module:engine/view/document~Document#event:selectionChange} event only if
- * a selection change was the only change in the document and the DOM selection is different from the view selection.
- *
- * This observer also manages the {@link module:engine/view/document~Document#isSelecting} property of the view document.
- *
- * Note that this observer is attached by the {@link module:engine/view/view~View} and is available by default.
- */
-export default class SelectionObserver extends Observer {
-    /**
-     * Instance of the mutation observer. Selection observer calls
-     * {@link module:engine/view/observer/mutationobserver~MutationObserver#flush} to ensure that the mutations will be handled
-     * before the {@link module:engine/view/document~Document#event:selectionChange} event is fired.
-     */
-    readonly mutationObserver: MutationObserver;
-    /**
-     * Instance of the focus observer. Focus observer calls
-     * {@link module:engine/view/observer/focusobserver~FocusObserver#flush} to mark the latest focus change as complete.
-     */
-    readonly focusObserver: FocusObserver;
-    /**
-     * Reference to the view {@link module:engine/view/documentselection~DocumentSelection} object used to compare
-     * new selection with it.
-     */
-    readonly selection: DocumentSelection;
-    /**
-     * Reference to the {@link module:engine/view/view~View#domConverter}.
-     */
-    readonly domConverter: DomConverter;
-    /**
-     * A set of documents which have added `selectionchange` listener to avoid adding a listener twice to the same
-     * document.
-     */
-    private readonly _documents;
-    /**
-     * Fires debounced event `selectionChangeDone`. It uses `lodash#debounce` method to delay function call.
-     */
-    private readonly _fireSelectionChangeDoneDebounced;
-    /**
-     * When called, starts clearing the {@link #_loopbackCounter} counter in time intervals. When the number of selection
-     * changes exceeds a certain limit within the interval of time, the observer will not fire `selectionChange` but warn about
-     * possible infinite selection loop.
-     */
-    private readonly _clearInfiniteLoopInterval;
-    /**
-     * Unlocks the `isSelecting` state of the view document in case the selection observer did not record this fact
-     * correctly (for whatever reason). It is a safeguard (paranoid check), that returns document to the normal state
-     * after a certain period of time (debounced, postponed by each selectionchange event).
-     */
-    private readonly _documentIsSelectingInactivityTimeoutDebounced;
-    /**
-     * Private property to check if the code does not enter infinite loop.
-     */
-    private _loopbackCounter;
-    constructor(view: View);
-    /**
-     * @inheritDoc
-     */
-    observe(domElement: HTMLElement): void;
-    /**
-     * @inheritDoc
-     */
-    stopObserving(domElement: HTMLElement): void;
-    /**
-     * @inheritDoc
-     */
-    destroy(): void;
-    private _reportInfiniteLoop;
-    /**
-     * Selection change listener. {@link module:engine/view/observer/mutationobserver~MutationObserver#flush Flush} mutations, check if
-     * a selection changes and fires {@link module:engine/view/document~Document#event:selectionChange} event on every change
-     * and {@link module:engine/view/document~Document#event:selectionChangeDone} when a selection stop changing.
-     *
-     * @param domEvent DOM event.
-     * @param domDocument DOM document.
-     */
-    private _handleSelectionChange;
-    /**
-     * Clears `SelectionObserver` internal properties connected with preventing infinite loop.
-     */
-    private _clearInfiniteLoop;
-}
-/**
- * The value of {@link ~ViewDocumentSelectionChangeEvent} and {@link ~ViewDocumentSelectionChangeDoneEvent} events.
- */
-export type ViewDocumentSelectionEventData = {
-    /**
-     * Old View selection which is {@link module:engine/view/document~Document#selection}.
-     */
-    oldSelection: DocumentSelection;
-    /**
-     * New View selection which is converted DOM selection.
-     */
-    newSelection: Selection;
-    /**
-     * Native DOM selection.
-     */
-    domSelection: DomSelection | null;
-};
-/**
- * Fired when a selection has changed. This event is fired only when the selection change was the only change that happened
- * in the document, and the old selection is different then the new selection.
- *
- * Introduced by {@link module:engine/view/observer/selectionobserver~SelectionObserver}.
- *
- * Note that because {@link module:engine/view/observer/selectionobserver~SelectionObserver} is attached by the
- * {@link module:engine/view/view~View} this event is available by default.
- *
- * @see module:engine/view/observer/selectionobserver~SelectionObserver
- * @eventName module:engine/view/document~Document#selectionChange
- */
-export type ViewDocumentSelectionChangeEvent = {
-    name: 'selectionChange';
-    args: [ViewDocumentSelectionEventData];
-};
-/**
- * Fired when selection stops changing.
- *
- * Introduced by {@link module:engine/view/observer/selectionobserver~SelectionObserver}.
- *
- * Note that because {@link module:engine/view/observer/selectionobserver~SelectionObserver} is attached by the
- * {@link module:engine/view/view~View} this event is available by default.
- *
- * @see module:engine/view/observer/selectionobserver~SelectionObserver
- * @eventName module:engine/view/document~Document#selectionChangeDone
- */
-export type ViewDocumentSelectionChangeDoneEvent = {
-    name: 'selectionChangeDone';
-    args: [ViewDocumentSelectionEventData];
-};
-export {};
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module engine/view/observer/selectionobserver
+ */
+import Observer from './observer';
+import MutationObserver from './mutationobserver';
+import type View from '../view';
+import type DocumentSelection from '../documentselection';
+import type DomConverter from '../domconverter';
+import type Selection from '../selection';
+import FocusObserver from './focusobserver';
+type DomSelection = globalThis.Selection;
+/**
+ * Selection observer class observes selection changes in the document. If a selection changes on the document this
+ * observer checks if the DOM selection is different from the {@link module:engine/view/document~Document#selection view selection}.
+ * The selection observer fires {@link module:engine/view/document~Document#event:selectionChange} event only if
+ * a selection change was the only change in the document and the DOM selection is different from the view selection.
+ *
+ * This observer also manages the {@link module:engine/view/document~Document#isSelecting} property of the view document.
+ *
+ * Note that this observer is attached by the {@link module:engine/view/view~View} and is available by default.
+ */
+export default class SelectionObserver extends Observer {
+    /**
+     * Instance of the mutation observer. Selection observer calls
+     * {@link module:engine/view/observer/mutationobserver~MutationObserver#flush} to ensure that the mutations will be handled
+     * before the {@link module:engine/view/document~Document#event:selectionChange} event is fired.
+     */
+    readonly mutationObserver: MutationObserver;
+    /**
+     * Instance of the focus observer. Focus observer calls
+     * {@link module:engine/view/observer/focusobserver~FocusObserver#flush} to mark the latest focus change as complete.
+     */
+    readonly focusObserver: FocusObserver;
+    /**
+     * Reference to the view {@link module:engine/view/documentselection~DocumentSelection} object used to compare
+     * new selection with it.
+     */
+    readonly selection: DocumentSelection;
+    /**
+     * Reference to the {@link module:engine/view/view~View#domConverter}.
+     */
+    readonly domConverter: DomConverter;
+    /**
+     * A set of documents which have added `selectionchange` listener to avoid adding a listener twice to the same
+     * document.
+     */
+    private readonly _documents;
+    /**
+     * Fires debounced event `selectionChangeDone`. It uses `lodash#debounce` method to delay function call.
+     */
+    private readonly _fireSelectionChangeDoneDebounced;
+    /**
+     * When called, starts clearing the {@link #_loopbackCounter} counter in time intervals. When the number of selection
+     * changes exceeds a certain limit within the interval of time, the observer will not fire `selectionChange` but warn about
+     * possible infinite selection loop.
+     */
+    private readonly _clearInfiniteLoopInterval;
+    /**
+     * Unlocks the `isSelecting` state of the view document in case the selection observer did not record this fact
+     * correctly (for whatever reason). It is a safeguard (paranoid check), that returns document to the normal state
+     * after a certain period of time (debounced, postponed by each selectionchange event).
+     */
+    private readonly _documentIsSelectingInactivityTimeoutDebounced;
+    /**
+     * Private property to check if the code does not enter infinite loop.
+     */
+    private _loopbackCounter;
+    constructor(view: View);
+    /**
+     * @inheritDoc
+     */
+    observe(domElement: HTMLElement): void;
+    /**
+     * @inheritDoc
+     */
+    stopObserving(domElement: HTMLElement): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    private _reportInfiniteLoop;
+    /**
+     * Selection change listener. {@link module:engine/view/observer/mutationobserver~MutationObserver#flush Flush} mutations, check if
+     * a selection changes and fires {@link module:engine/view/document~Document#event:selectionChange} event on every change
+     * and {@link module:engine/view/document~Document#event:selectionChangeDone} when a selection stop changing.
+     *
+     * @param domEvent DOM event.
+     * @param domDocument DOM document.
+     */
+    private _handleSelectionChange;
+    /**
+     * Clears `SelectionObserver` internal properties connected with preventing infinite loop.
+     */
+    private _clearInfiniteLoop;
+}
+/**
+ * The value of {@link ~ViewDocumentSelectionChangeEvent} and {@link ~ViewDocumentSelectionChangeDoneEvent} events.
+ */
+export type ViewDocumentSelectionEventData = {
+    /**
+     * Old View selection which is {@link module:engine/view/document~Document#selection}.
+     */
+    oldSelection: DocumentSelection;
+    /**
+     * New View selection which is converted DOM selection.
+     */
+    newSelection: Selection;
+    /**
+     * Native DOM selection.
+     */
+    domSelection: DomSelection | null;
+};
+/**
+ * Fired when a selection has changed. This event is fired only when the selection change was the only change that happened
+ * in the document, and the old selection is different then the new selection.
+ *
+ * Introduced by {@link module:engine/view/observer/selectionobserver~SelectionObserver}.
+ *
+ * Note that because {@link module:engine/view/observer/selectionobserver~SelectionObserver} is attached by the
+ * {@link module:engine/view/view~View} this event is available by default.
+ *
+ * @see module:engine/view/observer/selectionobserver~SelectionObserver
+ * @eventName module:engine/view/document~Document#selectionChange
+ */
+export type ViewDocumentSelectionChangeEvent = {
+    name: 'selectionChange';
+    args: [ViewDocumentSelectionEventData];
+};
+/**
+ * Fired when selection stops changing.
+ *
+ * Introduced by {@link module:engine/view/observer/selectionobserver~SelectionObserver}.
+ *
+ * Note that because {@link module:engine/view/observer/selectionobserver~SelectionObserver} is attached by the
+ * {@link module:engine/view/view~View} this event is available by default.
+ *
+ * @see module:engine/view/observer/selectionobserver~SelectionObserver
+ * @eventName module:engine/view/document~Document#selectionChangeDone
+ */
+export type ViewDocumentSelectionChangeDoneEvent = {
+    name: 'selectionChangeDone';
+    args: [ViewDocumentSelectionEventData];
+};
+export {};