@ckeditor/ckeditor5-engine 48.2.0 → 48.3.0-alpha.1

package/dist/view/document.d.ts

@@ -1,188 +1,186 @@
 /**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
+* @license Copyright (c) 2003-2026, 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/document
- */
-import { ViewDocumentSelection } from './documentselection.js';
-import { Collection } from '@ckeditor/ckeditor5-utils';
-import type { StylesProcessor } from './stylesmap.js';
-import { type ViewRootEditableElement } from './rooteditableelement.js';
-import { type ViewDowncastWriter } from './downcastwriter.js';
-declare const ViewDocument_base: import("@ckeditor/ckeditor5-utils").Mixed<{
-    new (): import("@ckeditor/ckeditor5-utils").Observable;
-    prototype: import("@ckeditor/ckeditor5-utils").Observable;
-}, import("@ckeditor/ckeditor5-utils").Emitter>;
+* @module engine/view/document
+*/
+import { ViewDocumentSelection } from "./documentselection.js";
+import { type BubblingEmitterMixinConstructor } from "./observer/bubblingemittermixin.js";
+import { Collection, type ObservableMixinConstructor } from "@ckeditor/ckeditor5-utils";
+import type { StylesProcessor } from "./stylesmap.js";
+import { type ViewRootEditableElement } from "./rooteditableelement.js";
+import { type ViewDowncastWriter } from "./downcastwriter.js";
+declare const ViewDocumentBase: BubblingEmitterMixinConstructor<ObservableMixinConstructor>;
 /**
- * Document class creates an abstract layer over the content editable area, contains a tree of view elements and
- * {@link module:engine/view/documentselection~ViewDocumentSelection view selection} associated with this document.
- */
-export declare class ViewDocument extends /* #__PURE__ */ ViewDocument_base {
-    /**
-     * Selection done on this document.
-     */
-    readonly selection: ViewDocumentSelection;
-    /**
-     * Roots of the view tree. Collection of the {@link module:engine/view/element~ViewElement view elements}.
-     *
-     * View roots are created as a result of binding between {@link module:engine/view/document~ViewDocument#roots} and
-     * {@link module:engine/model/document~ModelDocument#roots} and this is handled by
-     * {@link module:engine/controller/editingcontroller~EditingController}, so to create view root we need to create
-     * model root using {@link module:engine/model/document~ModelDocument#createRoot}.
-     */
-    readonly roots: Collection<ViewRootEditableElement>;
-    /**
-     * The styles processor instance used by this document when normalizing styles.
-     */
-    readonly stylesProcessor: StylesProcessor;
-    /**
-     * Defines whether document is in read-only mode.
-     *
-     * When document is read-ony then all roots are read-only as well and caret placed inside this root is hidden.
-     *
-     * @observable
-     */
-    isReadOnly: boolean;
-    /**
-     * True if document is focused.
-     *
-     * This property is updated by the {@link module:engine/view/observer/focusobserver~FocusObserver}.
-     * If the {@link module:engine/view/observer/focusobserver~FocusObserver} is disabled this property will not change.
-     *
-     * @readonly
-     * @observable
-     */
-    isFocused: boolean;
-    /**
-     * `true` while the user is making a selection in the document (e.g. holding the mouse button and moving the cursor).
-     * When they stop selecting, the property goes back to `false`.
-     *
-     * This property is updated by the {@link module:engine/view/observer/selectionobserver~SelectionObserver}.
-     *
-     * @readonly
-     * @observable
-     */
-    isSelecting: boolean;
-    /**
-     * True if composition is in progress inside the document.
-     *
-     * This property is updated by the {@link module:engine/view/observer/compositionobserver~CompositionObserver}.
-     * If the {@link module:engine/view/observer/compositionobserver~CompositionObserver} is disabled this property will not change.
-     *
-     * @readonly
-     * @observable
-     */
-    isComposing: boolean;
-    /**
-     * Post-fixer callbacks registered to the view document.
-     */
-    private readonly _postFixers;
-    /**
-     * Creates a Document instance.
-     *
-     * @param stylesProcessor The styles processor instance.
-     */
-    constructor(stylesProcessor: StylesProcessor);
-    /**
-     * Gets a {@link module:engine/view/document~ViewDocument#roots view root element} with the specified name. If the name is not
-     * specific "main" root is returned.
-     *
-     * @param name Name of the root.
-     * @returns The view root element with the specified name or null when there is no root of given name.
-     */
-    getRoot(name?: string): ViewRootEditableElement | null;
-    /**
-     * Returns an array with all roots added to the document.
-     */
-    getRoots(): Array<ViewRootEditableElement>;
-    /**
-     * Allows registering post-fixer callbacks. A post-fixers mechanism allows to update the view tree just before it is rendered
-     * to the DOM.
-     *
-     * Post-fixers are executed right after all changes from the outermost change block were applied but
-     * before the {@link module:engine/view/view~EditingView#event:render render event} is fired. If a post-fixer callback made
-     * a change, it should return `true`. When this happens, all post-fixers are fired again to check if something else should
-     * not be fixed in the new document tree state.
-     *
-     * View post-fixers are useful when you want to apply some fixes whenever the view structure changes. Keep in mind that
-     * changes executed in a view post-fixer should not break model-view mapping.
-     *
-     * The types of changes which should be safe:
-     *
-     * * adding or removing attribute from elements,
-     * * changes inside of {@link module:engine/view/uielement~ViewUIElement UI elements},
-     * * {@link module:engine/controller/editingcontroller~EditingController#reconvertItem marking some of the model elements to be
-     * re-converted}.
-     *
-     * Try to avoid changes which touch view structure:
-     *
-     * * you should not add or remove nor wrap or unwrap any view elements,
-     * * you should not change the editor data model in a view post-fixer.
-     *
-     * As a parameter, a post-fixer callback receives a {@link module:engine/view/downcastwriter~ViewDowncastWriter downcast writer}.
-     *
-     * Typically, a post-fixer will look like this:
-     *
-     * ```ts
-     * editor.editing.view.document.registerPostFixer( writer => {
-     * 	if ( checkSomeCondition() ) {
-     * 		writer.doSomething();
-     *
-     * 		// Let other post-fixers know that something changed.
-     * 		return true;
-     * 	}
-     *
-     * 	return false;
-     * } );
-     * ```
-     *
-     * Note that nothing happens right after you register a post-fixer (e.g. execute such a code in the console).
-     * That is because adding a post-fixer does not execute it.
-     * The post-fixer will be executed as soon as any change in the document needs to cause its rendering.
-     * If you want to re-render the editor's view after registering the post-fixer then you should do it manually by calling
-     * {@link module:engine/view/view~EditingView#forceRender `view.forceRender()`}.
-     *
-     * If you need to register a callback which is executed when DOM elements are already updated,
-     * use {@link module:engine/view/view~EditingView#event:render render event}.
-     */
-    registerPostFixer(postFixer: ViewDocumentPostFixer): void;
-    /**
-     * Destroys this instance. Makes sure that all observers are destroyed and listeners removed.
-     */
-    destroy(): void;
-    /**
-     * Performs post-fixer loops. Executes post-fixer callbacks as long as none of them has done any changes to the model.
-     *
-     * @internal
-     */
-    _callPostFixers(writer: ViewDowncastWriter): void;
+* Document class creates an abstract layer over the content editable area, contains a tree of view elements and
+* {@link module:engine/view/documentselection~ViewDocumentSelection view selection} associated with this document.
+*/
+export declare class ViewDocument extends ViewDocumentBase {
+	/**
+	* Selection done on this document.
+	*/
+	readonly selection: ViewDocumentSelection;
+	/**
+	* Roots of the view tree. Collection of the {@link module:engine/view/element~ViewElement view elements}.
+	*
+	* View roots are created as a result of binding between {@link module:engine/view/document~ViewDocument#roots} and
+	* {@link module:engine/model/document~ModelDocument#roots} and this is handled by
+	* {@link module:engine/controller/editingcontroller~EditingController}, so to create view root we need to create
+	* model root using {@link module:engine/model/document~ModelDocument#createRoot}.
+	*/
+	readonly roots: Collection<ViewRootEditableElement>;
+	/**
+	* The styles processor instance used by this document when normalizing styles.
+	*/
+	readonly stylesProcessor: StylesProcessor;
+	/**
+	* Defines whether document is in read-only mode.
+	*
+	* When document is read-ony then all roots are read-only as well and caret placed inside this root is hidden.
+	*
+	* @observable
+	*/
+	isReadOnly: boolean;
+	/**
+	* True if document is focused.
+	*
+	* This property is updated by the {@link module:engine/view/observer/focusobserver~FocusObserver}.
+	* If the {@link module:engine/view/observer/focusobserver~FocusObserver} is disabled this property will not change.
+	*
+	* @readonly
+	* @observable
+	*/
+	isFocused: boolean;
+	/**
+	* `true` while the user is making a selection in the document (e.g. holding the mouse button and moving the cursor).
+	* When they stop selecting, the property goes back to `false`.
+	*
+	* This property is updated by the {@link module:engine/view/observer/selectionobserver~SelectionObserver}.
+	*
+	* @readonly
+	* @observable
+	*/
+	isSelecting: boolean;
+	/**
+	* True if composition is in progress inside the document.
+	*
+	* This property is updated by the {@link module:engine/view/observer/compositionobserver~CompositionObserver}.
+	* If the {@link module:engine/view/observer/compositionobserver~CompositionObserver} is disabled this property will not change.
+	*
+	* @readonly
+	* @observable
+	*/
+	isComposing: boolean;
+	/**
+	* Post-fixer callbacks registered to the view document.
+	*/
+	private readonly _postFixers;
+	/**
+	* Creates a Document instance.
+	*
+	* @param stylesProcessor The styles processor instance.
+	*/
+	constructor(stylesProcessor: StylesProcessor);
+	/**
+	* Gets a {@link module:engine/view/document~ViewDocument#roots view root element} with the specified name. If the name is not
+	* specific "main" root is returned.
+	*
+	* @param name Name of the root.
+	* @returns The view root element with the specified name or null when there is no root of given name.
+	*/
+	getRoot(name?: string): ViewRootEditableElement | null;
+	/**
+	* Returns an array with all roots added to the document.
+	*/
+	getRoots(): Array<ViewRootEditableElement>;
+	/**
+	* Allows registering post-fixer callbacks. A post-fixers mechanism allows to update the view tree just before it is rendered
+	* to the DOM.
+	*
+	* Post-fixers are executed right after all changes from the outermost change block were applied but
+	* before the {@link module:engine/view/view~EditingView#event:render render event} is fired. If a post-fixer callback made
+	* a change, it should return `true`. When this happens, all post-fixers are fired again to check if something else should
+	* not be fixed in the new document tree state.
+	*
+	* View post-fixers are useful when you want to apply some fixes whenever the view structure changes. Keep in mind that
+	* changes executed in a view post-fixer should not break model-view mapping.
+	*
+	* The types of changes which should be safe:
+	*
+	* * adding or removing attribute from elements,
+	* * changes inside of {@link module:engine/view/uielement~ViewUIElement UI elements},
+	* * {@link module:engine/controller/editingcontroller~EditingController#reconvertItem marking some of the model elements to be
+	* re-converted}.
+	*
+	* Try to avoid changes which touch view structure:
+	*
+	* * you should not add or remove nor wrap or unwrap any view elements,
+	* * you should not change the editor data model in a view post-fixer.
+	*
+	* As a parameter, a post-fixer callback receives a {@link module:engine/view/downcastwriter~ViewDowncastWriter downcast writer}.
+	*
+	* Typically, a post-fixer will look like this:
+	*
+	* ```ts
+	* editor.editing.view.document.registerPostFixer( writer => {
+	* 	if ( checkSomeCondition() ) {
+	* 		writer.doSomething();
+	*
+	* 		// Let other post-fixers know that something changed.
+	* 		return true;
+	* 	}
+	*
+	* 	return false;
+	* } );
+	* ```
+	*
+	* Note that nothing happens right after you register a post-fixer (e.g. execute such a code in the console).
+	* That is because adding a post-fixer does not execute it.
+	* The post-fixer will be executed as soon as any change in the document needs to cause its rendering.
+	* If you want to re-render the editor's view after registering the post-fixer then you should do it manually by calling
+	* {@link module:engine/view/view~EditingView#forceRender `view.forceRender()`}.
+	*
+	* If you need to register a callback which is executed when DOM elements are already updated,
+	* use {@link module:engine/view/view~EditingView#event:render render event}.
+	*/
+	registerPostFixer(postFixer: ViewDocumentPostFixer): void;
+	/**
+	* Destroys this instance. Makes sure that all observers are destroyed and listeners removed.
+	*/
+	destroy(): void;
+	/**
+	* Performs post-fixer loops. Executes post-fixer callbacks as long as none of them has done any changes to the model.
+	*
+	* @internal
+	*/
+	_callPostFixers(writer: ViewDowncastWriter): void;
 }
 /**
- * Document PostFixer.
- *
- * @see module:engine/view/document~ViewDocument#registerPostFixer
- */
+* Document PostFixer.
+*
+* @see module:engine/view/document~ViewDocument#registerPostFixer
+*/
 export type ViewDocumentPostFixer = (writer: ViewDowncastWriter) => boolean;
 /**
- * Enum representing type of the change.
- *
- * Possible values:
- *
- * * `children` - for child list changes,
- * * `attributes` - for element attributes changes,
- * * `text` - for text nodes changes.
- */
-export type ViewDocumentChangeType = 'children' | 'attributes' | 'text';
+* Enum representing type of the change.
+*
+* Possible values:
+*
+* * `children` - for child list changes,
+* * `attributes` - for element attributes changes,
+* * `text` - for text nodes changes.
+*/
+export type ViewDocumentChangeType = "children" | "attributes" | "text";
 /**
- * Event fired whenever document content layout changes. It is fired whenever content is
- * {@link module:engine/view/view~EditingView#event:render rendered}, but should be also fired by observers in case of
- * other actions which may change layout, for instance when image loads.
- *
- * @eventName ~ViewDocument#layoutChanged
- */
+* Event fired whenever document content layout changes. It is fired whenever content is
+* {@link module:engine/view/view~EditingView#event:render rendered}, but should be also fired by observers in case of
+* other actions which may change layout, for instance when image loads.
+*
+* @eventName ~ViewDocument#layoutChanged
+*/
 export type ViewDocumentLayoutChangedEvent = {
-    name: 'layoutChanged';
-    args: [];
+	name: "layoutChanged";
+	args: [];
 };
 export {};