@ckeditor/ckeditor5-engine 44.1.0 → 44.2.0-alpha.1

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

@@ -1,93 +0,0 @@
-/**
- * @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
- */
-/**
- * @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-licensing-options
- */
-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 /* #__PURE__ */ 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 {};

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

@@ -1,151 +0,0 @@
-/**
- * @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
- */
-/**
- * @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-licensing-options
- */
-/**
- * @module engine/view/observer/selectionobserver
- */
-import Observer from './observer.js';
-import MutationObserver from './mutationobserver.js';
-import FocusObserver from './focusobserver.js';
-import type View from '../view.js';
-import type DocumentSelection from '../documentselection.js';
-import type DomConverter from '../domconverter.js';
-import type Selection from '../selection.js';
-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 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 {};

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

@@ -1,50 +0,0 @@
-/**
- * @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
- */
-/**
- * @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-licensing-options
- */
-/**
- * @module engine/view/observer/tabobserver
- */
-import type View from '../view.js';
-import Observer from './observer.js';
-import type { KeyEventData } from './keyobserver.js';
-import type { BubblingEvent } from './bubblingemittermixin.js';
-/**
- * Tab observer introduces the {@link module:engine/view/document~Document#event:tab `Document#tab`} event.
- *
- * Note that because {@link module:engine/view/observer/tabobserver~TabObserver} is attached by the
- * {@link module:engine/view/view~View}, this event is available by default.
- */
-export default class TabObserver extends Observer {
-    /**
-     * @inheritDoc
-     */
-    constructor(view: View);
-    /**
-     * @inheritDoc
-     */
-    observe(): void;
-    /**
-     * @inheritDoc
-     */
-    stopObserving(): void;
-}
-/**
- * Event fired when the user presses a tab key.
- *
- * Introduced by {@link module:engine/view/observer/tabobserver~TabObserver}.
- *
- * Note that because {@link module:engine/view/observer/tabobserver~TabObserver} is attached by the
- * {@link module:engine/view/view~View}, this event is available by default.
- *
- * @eventName module:engine/view/document~Document#tab
- * @param data
- */
-export type ViewDocumentTabEvent = BubblingEvent<{
-    name: 'tab';
-    args: [data: KeyEventData];
-}>;

package/dist/view/placeholder.d.ts

@@ -1,100 +0,0 @@
-/**
- * @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
- */
-/**
- * @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-licensing-options
- */
-/**
- * @module engine/view/placeholder
- */
-import '../../theme/placeholder.css';
-import type DowncastWriter from './downcastwriter.js';
-import type EditableElement from './editableelement.js';
-import type Element from './element.js';
-import type View from './view.js';
-/**
- * A helper that enables a placeholder on the provided view element (also updates its visibility).
- * The placeholder is a CSS pseudo–element (with a text content) attached to the element.
- *
- * To change the placeholder text, change value of the `placeholder` property in the provided `element`.
- *
- * To disable the placeholder, use {@link module:engine/view/placeholder~disablePlaceholder `disablePlaceholder()`} helper.
- *
- * @param options Configuration options of the placeholder.
- * @param options.view Editing view instance.
- * @param options.element Element that will gain a placeholder. See `options.isDirectHost` to learn more.
- * @param options.isDirectHost If set `false`, the placeholder will not be enabled directly
- * in the passed `element` but in one of its children (selected automatically, i.e. a first empty child element).
- * Useful when attaching placeholders to elements that can host other elements (not just text), for instance,
- * editable root elements.
- * @param options.text Placeholder text. It's **deprecated** and will be removed soon. Use
- * {@link module:engine/view/placeholder~PlaceholderableElement#placeholder `options.element.placeholder`} instead.
- * @param options.keepOnFocus If set `true`, the placeholder stay visible when the host element is focused.
- */
-export declare function enablePlaceholder({ view, element, text, isDirectHost, keepOnFocus }: {
-    view: View;
-    element: PlaceholderableElement | EditableElement;
-    isDirectHost?: boolean;
-    text?: string;
-    keepOnFocus?: boolean;
-}): void;
-/**
- * Disables the placeholder functionality from a given element.
- *
- * See {@link module:engine/view/placeholder~enablePlaceholder `enablePlaceholder()`} to learn more.
- */
-export declare function disablePlaceholder(view: View, element: Element): void;
-/**
- * Shows a placeholder in the provided element by changing related attributes and CSS classes.
- *
- * **Note**: This helper will not update the placeholder visibility nor manage the
- * it in any way in the future. What it does is a one–time state change of an element. Use
- * {@link module:engine/view/placeholder~enablePlaceholder `enablePlaceholder()`} and
- * {@link module:engine/view/placeholder~disablePlaceholder `disablePlaceholder()`} for full
- * placeholder functionality.
- *
- * **Note**: This helper will blindly show the placeholder directly in the root editable element if
- * one is passed, which could result in a visual clash if the editable element has some children
- * (for instance, an empty paragraph). Use {@link module:engine/view/placeholder~enablePlaceholder `enablePlaceholder()`}
- * in that case or make sure the correct element is passed to the helper.
- *
- * @returns `true`, if any changes were made to the `element`.
- */
-export declare function showPlaceholder(writer: DowncastWriter, element: Element): boolean;
-/**
- * Hides a placeholder in the element by changing related attributes and CSS classes.
- *
- * **Note**: This helper will not update the placeholder visibility nor manage the
- * it in any way in the future. What it does is a one–time state change of an element. Use
- * {@link module:engine/view/placeholder~enablePlaceholder `enablePlaceholder()`} and
- * {@link module:engine/view/placeholder~disablePlaceholder `disablePlaceholder()`} for full
- * placeholder functionality.
- *
- * @returns `true`, if any changes were made to the `element`.
- */
-export declare function hidePlaceholder(writer: DowncastWriter, element: Element): boolean;
-/**
- * Checks if a placeholder should be displayed in the element.
- *
- * **Note**: This helper will blindly check the possibility of showing a placeholder directly in the
- * root editable element if one is passed, which may not be the expected result. If an element can
- * host other elements (not just text), most likely one of its children should be checked instead
- * because it will be the final host for the placeholder. Use
- * {@link module:engine/view/placeholder~enablePlaceholder `enablePlaceholder()`} in that case or make
- * sure the correct element is passed to the helper.
- *
- * @param element Element that holds the placeholder.
- * @param keepOnFocus Focusing the element will keep the placeholder visible.
- */
-export declare function needsPlaceholder(element: Element, keepOnFocus: boolean): boolean;
-/**
- * Element that could have a placeholder.
- */
-export interface PlaceholderableElement extends Element {
-    /**
-     * The text of element's placeholder.
-     */
-    placeholder?: string;
-}

package/dist/view/position.d.ts

@@ -1,192 +0,0 @@
-/**
- * @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
- */
-/**
- * @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-licensing-options
- */
-/**
- * @module engine/view/position
- */
-import TypeCheckable from './typecheckable.js';
-import EditableElement from './editableelement.js';
-import type DocumentFragment from './documentfragment.js';
-import type Item from './item.js';
-import type Node from './node.js';
-import { default as TreeWalker, type TreeWalkerValue, type TreeWalkerOptions } from './treewalker.js';
-/**
- * Position in the view tree. Position is represented by its parent node and an offset in this parent.
- *
- * In order to create a new position instance use the `createPosition*()` factory methods available in:
- *
- * * {@link module:engine/view/view~View}
- * * {@link module:engine/view/downcastwriter~DowncastWriter}
- * * {@link module:engine/view/upcastwriter~UpcastWriter}
- */
-export default class Position extends TypeCheckable {
-    /**
-     * Position parent.
-     */
-    readonly parent: Node | DocumentFragment;
-    /**
-     * Position offset.
-     */
-    offset: number;
-    /**
-     * Creates a position.
-     *
-     * @param parent Position parent.
-     * @param offset Position offset.
-     */
-    constructor(parent: Node | DocumentFragment, offset: number);
-    /**
-     * Node directly after the position. Equals `null` when there is no node after position or position is located
-     * inside text node.
-     */
-    get nodeAfter(): Node | null;
-    /**
-     * Node directly before the position. Equals `null` when there is no node before position or position is located
-     * inside text node.
-     */
-    get nodeBefore(): Node | null;
-    /**
-     * Is `true` if position is at the beginning of its {@link module:engine/view/position~Position#parent parent}, `false` otherwise.
-     */
-    get isAtStart(): boolean;
-    /**
-     * Is `true` if position is at the end of its {@link module:engine/view/position~Position#parent parent}, `false` otherwise.
-     */
-    get isAtEnd(): boolean;
-    /**
-     * Position's root, that is the root of the position's parent element.
-     */
-    get root(): Node | DocumentFragment;
-    /**
-     * {@link module:engine/view/editableelement~EditableElement EditableElement} instance that contains this position, or `null` if
-     * position is not inside an editable element.
-     */
-    get editableElement(): EditableElement | null;
-    /**
-     * Returns a new instance of Position with offset incremented by `shift` value.
-     *
-     * @param shift How position offset should get changed. Accepts negative values.
-     * @returns Shifted position.
-     */
-    getShiftedBy(shift: number): Position;
-    /**
-     * Gets the farthest position which matches the callback using
-     * {@link module:engine/view/treewalker~TreeWalker TreeWalker}.
-     *
-     * For example:
-     *
-     * ```ts
-     * getLastMatchingPosition( value => value.type == 'text' ); // <p>{}foo</p> -> <p>foo[]</p>
-     * getLastMatchingPosition( value => value.type == 'text', { direction: 'backward' } ); // <p>foo[]</p> -> <p>{}foo</p>
-     * getLastMatchingPosition( value => false ); // Do not move the position.
-     * ```
-     *
-     * @param skip Callback function. Gets {@link module:engine/view/treewalker~TreeWalkerValue} and should
-     * return `true` if the value should be skipped or `false` if not.
-     * @param options Object with configuration options. See {@link module:engine/view/treewalker~TreeWalker}.
-     * @returns The position after the last item which matches the `skip` callback test.
-     */
-    getLastMatchingPosition(skip: (value: TreeWalkerValue) => boolean, options?: TreeWalkerOptions): Position;
-    /**
-     * Returns ancestors array of this position, that is this position's parent and it's ancestors.
-     *
-     * @returns Array with ancestors.
-     */
-    getAncestors(): Array<Node | DocumentFragment>;
-    /**
-     * Returns a {@link module:engine/view/node~Node} or {@link module:engine/view/documentfragment~DocumentFragment}
-     * which is a common ancestor of both positions.
-     */
-    getCommonAncestor(position: Position): Node | DocumentFragment | null;
-    /**
-     * Checks whether this position equals given position.
-     *
-     * @param otherPosition Position to compare with.
-     * @returns True if positions are same.
-     */
-    isEqual(otherPosition: Position): boolean;
-    /**
-     * Checks whether this position is located before given position. When method returns `false` it does not mean that
-     * this position is after give one. Two positions may be located inside separate roots and in that situation this
-     * method will still return `false`.
-     *
-     * @see module:engine/view/position~Position#isAfter
-     * @see module:engine/view/position~Position#compareWith
-     * @param otherPosition Position to compare with.
-     * @returns Returns `true` if this position is before given position.
-     */
-    isBefore(otherPosition: Position): boolean;
-    /**
-     * Checks whether this position is located after given position. When method returns `false` it does not mean that
-     * this position is before give one. Two positions may be located inside separate roots and in that situation this
-     * method will still return `false`.
-     *
-     * @see module:engine/view/position~Position#isBefore
-     * @see module:engine/view/position~Position#compareWith
-     * @param otherPosition Position to compare with.
-     * @returns Returns `true` if this position is after given position.
-     */
-    isAfter(otherPosition: Position): boolean;
-    /**
-     * Checks whether this position is before, after or in same position that other position. Two positions may be also
-     * different when they are located in separate roots.
-     *
-     * @param otherPosition Position to compare with.
-     */
-    compareWith(otherPosition: Position): PositionRelation;
-    /**
-     * Creates a {@link module:engine/view/treewalker~TreeWalker TreeWalker} instance with this positions as a start position.
-     *
-     * @param options Object with configuration options. See {@link module:engine/view/treewalker~TreeWalker}
-     */
-    getWalker(options?: TreeWalkerOptions): TreeWalker;
-    /**
-     * Clones this position.
-     */
-    clone(): Position;
-    /**
-     * Creates position at the given location. The location can be specified as:
-     *
-     * * a {@link module:engine/view/position~Position position},
-     * * parent element and offset (offset defaults to `0`),
-     * * parent element and `'end'` (sets position at the end of that element),
-     * * {@link module:engine/view/item~Item view item} and `'before'` or `'after'` (sets position before or after given view item).
-     *
-     * This method is a shortcut to other constructors such as:
-     *
-     * * {@link module:engine/view/position~Position._createBefore},
-     * * {@link module:engine/view/position~Position._createAfter}.
-     *
-     * @internal
-     * @param offset Offset or one of the flags. Used only when first parameter is a {@link module:engine/view/item~Item view item}.
-     */
-    static _createAt(itemOrPosition: Item | Position, offset?: PositionOffset): Position;
-    /**
-     * Creates a new position after given view item.
-     *
-     * @internal
-     * @param item View item after which the position should be located.
-     */
-    static _createAfter(item: Item): Position;
-    /**
-     * Creates a new position before given view item.
-     *
-     * @internal
-     * @param item View item before which the position should be located.
-     */
-    static _createBefore(item: Item): Position;
-}
-/**
- * A flag indicating whether this position is `'before'` or `'after'` or `'same'` as given position.
- * If positions are in different roots `'different'` flag is returned.
- */
-export type PositionRelation = 'before' | 'after' | 'same' | 'different';
-/**
- * Offset or one of the flags.
- */
-export type PositionOffset = number | 'before' | 'after' | 'end';