@ckeditor/ckeditor5-engine 41.2.0 → 41.3.0-alpha.0

package/dist/types/view/observer/fakeselectionobserver.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/fakeselectionobserver
+ */
+import Observer from './observer.js';
+import type View from '../view.js';
+/**
+ * Fake selection observer class. If view selection is fake it is placed in dummy DOM container. This observer listens
+ * on {@link module:engine/view/document~Document#event:keydown keydown} events and handles moving fake view selection to the correct place
+ * if arrow keys are pressed.
+ * Fires {@link module:engine/view/document~Document#event:selectionChange selectionChange event} simulating natural behaviour of
+ * {@link module:engine/view/observer/selectionobserver~SelectionObserver SelectionObserver}.
+ */
+export default class FakeSelectionObserver extends Observer {
+    /**
+     * Fires debounced event `selectionChangeDone`. It uses `lodash#debounce` method to delay function call.
+     */
+    private readonly _fireSelectionChangeDoneDebounced;
+    /**
+     * Creates new FakeSelectionObserver instance.
+     */
+    constructor(view: View);
+    /**
+     * @inheritDoc
+     */
+    observe(): void;
+    /**
+     * @inheritDoc
+     */
+    stopObserving(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Handles collapsing view selection according to given key code. If left or up key is provided - new selection will be
+     * collapsed to left. If right or down key is pressed - new selection will be collapsed to right.
+     *
+     * This method fires {@link module:engine/view/document~Document#event:selectionChange} and
+     * {@link module:engine/view/document~Document#event:selectionChangeDone} events imitating behaviour of
+     * {@link module:engine/view/observer/selectionobserver~SelectionObserver}.
+     */
+    private _handleSelectionMove;
+}

package/dist/types/view/observer/focusobserver.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/focusobserver
+ */
+import DomEventObserver from './domeventobserver.js';
+import type DomEventData from './domeventdata.js';
+import type View from '../view.js';
+/**
+ * {@link module:engine/view/document~Document#event:focus Focus}
+ * and {@link module:engine/view/document~Document#event:blur blur} events observer.
+ * Focus observer handle also {@link module:engine/view/rooteditableelement~RootEditableElement#isFocused isFocused} property of the
+ * {@link module:engine/view/rooteditableelement~RootEditableElement root elements}.
+ *
+ * Note that this observer is attached by the {@link module:engine/view/view~View} and is available by default.
+ */
+export default class FocusObserver extends DomEventObserver<'focus' | 'blur'> {
+    /**
+     * Identifier of the timeout currently used by focus listener to delay rendering execution.
+     */
+    private _renderTimeoutId;
+    /**
+     * Set to `true` if the document is in the process of setting the focus.
+     *
+     * The flag is used to indicate that setting the focus is in progress.
+     */
+    private _isFocusChanging;
+    /**
+     * @inheritDoc
+     */
+    readonly domEventType: readonly ["focus", "blur"];
+    /**
+     * @inheritDoc
+     */
+    constructor(view: View);
+    /**
+     * Finishes setting the document focus state.
+     */
+    flush(): void;
+    /**
+     * @inheritDoc
+     */
+    onDomEvent(domEvent: FocusEvent): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+}
+/**
+ * Fired when one of the editables gets focus.
+ *
+ * Introduced by {@link module:engine/view/observer/focusobserver~FocusObserver}.
+ *
+ * Note that because {@link module:engine/view/observer/focusobserver~FocusObserver} is attached by the
+ * {@link module:engine/view/view~View} this event is available by default.
+ *
+ * @see module:engine/view/observer/focusobserver~FocusObserver
+ * @eventName module:engine/view/document~Document#focus
+ * @param data Event data.
+ */
+export type ViewDocumentFocusEvent = {
+    name: 'focus';
+    args: [data: DomEventData<FocusEvent>];
+};
+/**
+ * Fired when one of the editables loses focus.
+ *
+ * Introduced by {@link module:engine/view/observer/focusobserver~FocusObserver}.
+ *
+ * Note that because {@link module:engine/view/observer/focusobserver~FocusObserver} is attached by the
+ * {@link module:engine/view/view~View} this event is available by default.
+ *
+ * @see module:engine/view/observer/focusobserver~FocusObserver
+ * @eventName module:engine/view/document~Document#blur
+ * @param data Event data.
+ */
+export type ViewDocumentBlurEvent = {
+    name: 'blur';
+    args: [data: DomEventData<FocusEvent>];
+};

package/dist/types/view/observer/inputobserver.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/inputobserver
+ */
+import DomEventObserver from './domeventobserver.js';
+import type DomEventData from './domeventdata.js';
+import type ViewRange from '../range.js';
+import DataTransfer from '../datatransfer.js';
+/**
+ * Observer for events connected with data input.
+ *
+ * **Note**: This observer is attached by {@link module:engine/view/view~View} and available by default in all
+ * editor instances.
+ */
+export default class InputObserver extends DomEventObserver<'beforeinput'> {
+    /**
+     * @inheritDoc
+     */
+    readonly domEventType: "beforeinput";
+    /**
+     * @inheritDoc
+     */
+    onDomEvent(domEvent: InputEvent): void;
+}
+/**
+ * Fired before the web browser inputs, deletes, or formats some data.
+ *
+ * This event is introduced by {@link module:engine/view/observer/inputobserver~InputObserver} and available
+ * by default in all editor instances (attached by {@link module:engine/view/view~View}).
+ *
+ * @see module:engine/view/observer/inputobserver~InputObserver
+ * @eventName module:engine/view/document~Document#beforeinput
+ * @param data Event data containing detailed information about the event.
+ */
+export type ViewDocumentInputEvent = {
+    name: 'beforeinput';
+    args: [data: InputEventData];
+};
+/**
+ * The value of the {@link ~ViewDocumentInputEvent} event.
+ */
+export interface InputEventData extends DomEventData<InputEvent> {
+    /**
+     * The type of the input event (e.g. "insertText" or "deleteWordBackward"). Corresponds to native `InputEvent#inputType`.
+     */
+    readonly inputType: string;
+    /**
+     * A unified text data passed along with the input event. Depending on:
+     *
+     * * the web browser and input events implementation (for instance [Level 1](https://www.w3.org/TR/input-events-1/) or
+     * [Level 2](https://www.w3.org/TR/input-events-2/)),
+     * * {@link module:engine/view/observer/inputobserver~InputEventData#inputType input type}
+     *
+     * text data is sometimes passed in the `data` and sometimes in the `dataTransfer` property.
+     *
+     * * If `InputEvent#data` was set, this property reflects its value.
+     * * If `InputEvent#data` is unavailable, this property contains the `'text/plain'` data from
+     * {@link module:engine/view/observer/inputobserver~InputEventData#dataTransfer}.
+     * * If the event ({@link module:engine/view/observer/inputobserver~InputEventData#inputType input type})
+     * provides no data whatsoever, this property is `null`.
+     */
+    readonly data: string | null;
+    /**
+     * The data transfer instance of the input event. Corresponds to native `InputEvent#dataTransfer`.
+     *
+     * The value is `null` when no `dataTransfer` was passed along with the input event.
+     */
+    readonly dataTransfer: DataTransfer;
+    /**
+     * A flag indicating that the `beforeinput` event was fired during composition.
+     *
+     * Corresponds to the
+     * {@link module:engine/view/document~Document#event:compositionstart},
+     * {@link module:engine/view/document~Document#event:compositionupdate},
+     * and {@link module:engine/view/document~Document#event:compositionend } trio.
+     */
+    readonly isComposing: boolean;
+    /**
+     * Editing {@link module:engine/view/range~Range view ranges} corresponding to DOM ranges provided by the web browser
+     * (as returned by `InputEvent#getTargetRanges()`).
+     */
+    readonly targetRanges: Array<ViewRange>;
+}

package/dist/types/view/observer/keyobserver.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/keyobserver
+ */
+import DomEventObserver from './domeventobserver.js';
+import type DomEventData from './domeventdata.js';
+import { type KeystrokeInfo } from '@ckeditor/ckeditor5-utils';
+/**
+ * Observer for events connected with pressing keyboard keys.
+ *
+ * Note that this observer is attached by the {@link module:engine/view/view~View} and is available by default.
+ */
+export default class KeyObserver extends DomEventObserver<'keydown' | 'keyup', KeystrokeInfo & {
+    keystroke: number;
+}> {
+    /**
+     * @inheritDoc
+     */
+    readonly domEventType: readonly ["keydown", "keyup"];
+    /**
+     * @inheritDoc
+     */
+    onDomEvent(domEvt: KeyboardEvent): void;
+}
+/**
+ * Fired when a key has been pressed.
+ *
+ * Introduced by {@link module:engine/view/observer/keyobserver~KeyObserver}.
+ *
+ * Note that because {@link module:engine/view/observer/keyobserver~KeyObserver} is attached by the
+ * {@link module:engine/view/view~View} this event is available by default.
+ *
+ * @see module:engine/view/observer/keyobserver~KeyObserver
+ * @eventName module:engine/view/document~Document#keydown
+ */
+export type ViewDocumentKeyDownEvent = {
+    name: 'keydown';
+    args: [data: KeyEventData];
+};
+/**
+ * Fired when a key has been released.
+ *
+ * Introduced by {@link module:engine/view/observer/keyobserver~KeyObserver}.
+ *
+ * Note that because {@link module:engine/view/observer/keyobserver~KeyObserver} is attached by the
+ * {@link module:engine/view/view~View} this event is available by default.
+ *
+ * @see module:engine/view/observer/keyobserver~KeyObserver
+ * @eventName module:engine/view/document~Document#keyup
+ */
+export type ViewDocumentKeyUpEvent = {
+    name: 'keyup';
+    args: [data: KeyEventData];
+};
+/**
+ * The value of both events - {@link ~ViewDocumentKeyDownEvent} and {@link ~ViewDocumentKeyUpEvent}.
+ */
+export interface KeyEventData extends DomEventData<KeyboardEvent>, KeystrokeInfo {
+    /**
+     * Code of the whole keystroke. See {@link module:utils/keyboard~getCode}.
+     */
+    keystroke: number;
+}

package/dist/types/view/observer/mouseobserver.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/mouseobserver
+ */
+import DomEventObserver from './domeventobserver.js';
+import type DomEventData from './domeventdata.js';
+/**
+ * Mouse events observer.
+ *
+ * Note that this observer is not available by default. To make it available it needs to be added to
+ * {@link module:engine/view/view~View} by {@link module:engine/view/view~View#addObserver} method.
+ */
+export default class MouseObserver extends DomEventObserver<'mousedown' | 'mouseup' | 'mouseover' | 'mouseout'> {
+    /**
+     * @inheritDoc
+     */
+    readonly domEventType: readonly ["mousedown", "mouseup", "mouseover", "mouseout"];
+    /**
+     * @inheritDoc
+     */
+    onDomEvent(domEvent: MouseEvent): void;
+}
+/**
+ * Fired when the mouse button is pressed down on one of the editing roots of the editor.
+ *
+ * Introduced by {@link module:engine/view/observer/mouseobserver~MouseObserver}.
+ *
+ * Note that this event is not available by default. To make it available, {@link module:engine/view/observer/mouseobserver~MouseObserver}
+ * needs to be added to {@link module:engine/view/view~View} by the {@link module:engine/view/view~View#addObserver} method.
+ *
+ * @see module:engine/view/observer/mouseobserver~MouseObserver
+ * @eventName module:engine/view/document~Document#mousedown
+ * @param data The event data.
+ */
+export type ViewDocumentMouseDownEvent = {
+    name: 'mousedown';
+    args: [data: DomEventData<MouseEvent>];
+};
+/**
+ * Fired when the mouse button is released over one of the editing roots of the editor.
+ *
+ * Introduced by {@link module:engine/view/observer/mouseobserver~MouseObserver}.
+ *
+ * Note that this event is not available by default. To make it available, {@link module:engine/view/observer/mouseobserver~MouseObserver}
+ * needs to be added to {@link module:engine/view/view~View} by the {@link module:engine/view/view~View#addObserver} method.
+ *
+ * @see module:engine/view/observer/mouseobserver~MouseObserver
+ * @eventName module:engine/view/document~Document#mouseup
+ * @param  data The event data.
+ */
+export type ViewDocumentMouseUpEvent = {
+    name: 'mouseup';
+    args: [data: DomEventData<MouseEvent>];
+};
+/**
+ * Fired when the mouse is over one of the editing roots of the editor.
+ *
+ * Introduced by {@link module:engine/view/observer/mouseobserver~MouseObserver}.
+ *
+ * Note that this event is not available by default. To make it available, {@link module:engine/view/observer/mouseobserver~MouseObserver}
+ * needs to be added to {@link module:engine/view/view~View} by the {@link module:engine/view/view~View#addObserver} method.
+ *
+ * @see module:engine/view/observer/mouseobserver~MouseObserver
+ * @eventName module:engine/view/document~Document#mouseover
+ * @param  data The event data.
+ */
+export type ViewDocumentMouseOverEvent = {
+    name: 'mouseover';
+    args: [data: DomEventData<MouseEvent>];
+};
+/**
+ * Fired when the mouse is moved out of the one of the editing roots of the editor.
+ *
+ * Introduced by {@link module:engine/view/observer/mouseobserver~MouseObserver}.
+ *
+ * Note that this event is not available by default. To make it available, {@link module:engine/view/observer/mouseobserver~MouseObserver}
+ * needs to be added to {@link module:engine/view/view~View} by the {@link module:engine/view/view~View#addObserver} method.
+ *
+ * @see module:engine/view/observer/mouseobserver~MouseObserver
+ * @eventName module:engine/view/document~Document#mouseout
+ * @param  data The event data.
+ */
+export type ViewDocumentMouseOutEvent = {
+    name: 'mouseout';
+    args: [data: DomEventData<MouseEvent>];
+};

package/dist/types/view/observer/mutationobserver.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/mutationobserver
+ */
+import Observer from './observer.js';
+import type DomConverter from '../domconverter.js';
+import type Renderer from '../renderer.js';
+import type View from '../view.js';
+/**
+ * Mutation observer's role is to watch for any DOM changes inside the editor that weren't
+ * done by the editor's {@link module:engine/view/renderer~Renderer} itself and reverting these changes.
+ *
+ * It does this by observing all mutations in the DOM, marking related view elements as changed and calling
+ * {@link module:engine/view/renderer~Renderer#render}. Because all mutated nodes are marked as
+ * "to be rendered" and the {@link module:engine/view/renderer~Renderer#render `render()`} method is called,
+ * all changes are reverted in the DOM (the DOM is synced with the editor's view structure).
+ *
+ * Note that this observer is attached by the {@link module:engine/view/view~View} and is available by default.
+ */
+export default class MutationObserver extends Observer {
+    /**
+     * Reference to the {@link module:engine/view/view~View#domConverter}.
+     */
+    readonly domConverter: DomConverter;
+    /**
+     * Reference to the {@link module:engine/view/view~View#_renderer}.
+     */
+    readonly renderer: Renderer;
+    /**
+     * Native mutation observer config.
+     */
+    private readonly _config;
+    /**
+     * Observed DOM elements.
+     */
+    private readonly _domElements;
+    /**
+     * Native mutation observer.
+     */
+    private _mutationObserver;
+    /**
+     * @inheritDoc
+     */
+    constructor(view: View);
+    /**
+     * Synchronously handles mutations and empties the queue.
+     */
+    flush(): void;
+    /**
+     * @inheritDoc
+     */
+    observe(domElement: HTMLElement): void;
+    /**
+     * @inheritDoc
+     */
+    stopObserving(domElement: HTMLElement): void;
+    /**
+     * @inheritDoc
+     */
+    enable(): void;
+    /**
+     * @inheritDoc
+     */
+    disable(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Handles mutations. Mark view elements to sync and call render.
+     *
+     * @param domMutations Array of native mutations.
+     */
+    private _onMutations;
+    /**
+     * Checks if mutation was generated by the browser inserting bogus br on the end of the block element.
+     * Such mutations are generated while pressing space or performing native spellchecker correction
+     * on the end of the block element in Firefox browser.
+     *
+     * @param mutation Native mutation object.
+     */
+    private _isBogusBrMutation;
+}

package/dist/types/view/observer/observer.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import type Document from '../document.js';
+import type View from '../view.js';
+declare const Observer_base: {
+    new (): import("@ckeditor/ckeditor5-utils").DomEmitter;
+    prototype: import("@ckeditor/ckeditor5-utils").DomEmitter;
+};
+/**
+ * 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 abstract class Observer extends Observer_base {
+    /**
+     * An instance of the view controller.
+     */
+    readonly view: View;
+    /**
+     * A reference to the {@link module:engine/view/document~Document} object.
+     */
+    readonly document: Document;
+    /**
+     * The state of the observer. If it is disabled, no events will be fired.
+     */
+    private _isEnabled;
+    /**
+     * Creates an instance of the observer.
+     */
+    constructor(view: View);
+    /**
+     * The state of the observer. If it is disabled, no events will be fired.
+     */
+    get isEnabled(): boolean;
+    /**
+     * 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(): void;
+    /**
+     * 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(): void;
+    /**
+     * Disables and destroys the observer, among others removes event listeners created by the observer.
+     */
+    destroy(): void;
+    /**
+     * 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: Node | null): boolean;
+    /**
+     * Starts observing given DOM element.
+     *
+     * @param domElement DOM element to observe.
+     * @param name The name of the related root element.
+     */
+    abstract observe(domElement: HTMLElement, name: string): void;
+    /**
+     * Stops observing given DOM element.
+     */
+    abstract stopObserving(domElement: HTMLElement): void;
+}
+/**
+ * The constructor of {@link ~Observer} subclass.
+ */
+export type ObserverConstructor = new (view: View) => Observer;
+export {};