@ckeditor/ckeditor5-engine 0.0.0-internal-20241017.0

package/CHANGELOG.md

@@ -0,0 +1,4 @@
+Changelog
+=========
+
+All changes in the package are documented in https://github.com/ckeditor/ckeditor5/blob/master/CHANGELOG.md.

package/LICENSE.md

@@ -0,0 +1,21 @@
+Software License Agreement
+==========================
+
+**CKEditor&nbsp;5 editing engine** – https://github.com/ckeditor/ckeditor5-engine <br>
+Copyright (c) 2003–2024, [CKSource Holding sp. z o.o.](https://cksource.com) All rights reserved.
+
+Licensed under the terms of [GNU General Public License Version 2 or later](http://www.gnu.org/licenses/gpl.html).
+
+Sources of Intellectual Property Included in CKEditor
+-----------------------------------------------------
+
+Where not otherwise indicated, all CKEditor content is authored by CKSource engineers and consists of CKSource-owned intellectual property. In some specific instances, CKEditor will incorporate work done by developers outside of CKSource with their express permission.
+
+The following libraries are included in CKEditor under the [MIT license](https://opensource.org/licenses/MIT):
+
+* Lodash - Copyright (c) JS Foundation and other contributors https://js.foundation/. Based on Underscore.js, copyright Jeremy Ashkenas, DocumentCloud and Investigative Reporters & Editors http://underscorejs.org/.
+
+Trademarks
+----------
+
+**CKEditor** is a trademark of [CKSource Holding sp. z o.o.](https://cksource.com) All other brand and product names are trademarks, registered trademarks, or service marks of their respective holders.

package/README.md

@@ -0,0 +1,36 @@
+CKEditor 5 editing engine
+========================================
+
+[![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-engine.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-engine)
+[![Coverage Status](https://coveralls.io/repos/github/ckeditor/ckeditor5/badge.svg?branch=master)](https://coveralls.io/github/ckeditor/ckeditor5?branch=master)
+[![Build Status](https://travis-ci.com/ckeditor/ckeditor5.svg?branch=master)](https://app.travis-ci.com/github/ckeditor/ckeditor5)
+
+The CKEditor 5 editing engine implements a flexible MVC-based architecture for creating rich text editing features.
+
+## Architecture overview
+
+* **Custom data model.** CKEditor 5 implements a tree-structured custom data model, designed to fit multiple requirements such as enabling real-time collaboration and complex editing features (like tables or nested blocks).
+* **Virtual DOM.** CKEditor 5's editing engine features a custom, editing-oriented virtual DOM implementation that aims to hide browser quirks from your sight. **No more `contentEditable` nightmares!**
+* **Real-time collaborative editing**. The editor implements Operational Transformation for the tree-structured model as well as many other mechanisms which were required to create a seamless collaborative UX. Additionally, we provide cloud infrastructure and plugins enabling real-time collaborative editing in your application! [Check the collaboration demo](https://ckeditor.com/docs/ckeditor5/latest/features/collaboration/overview.html).
+* **Extensible.** The entire editor architecture was designed for maximum flexibility. The code is event-based and highly decoupled, allowing you to plug in or replace selected pieces. Features do not directly depend on each other and communicate in standardized ways.
+* **Schema-less core**. The core makes minimal assumptions and can be controlled through the schema. This leaves all decisions to plugins and to you.
+* **Modular architecture.** Not only can the core modules be reused and recomposed but even the features were implemented in a highly granular way. Feel like running a headless CKEditor 5 with a couple of features in Node.js? Not a problem!
+* **Framework for building rich-text editors.** Every use case is different and every editor needs to fulfill different goals. Therefore, we give you the freedom to create your own editors with custom-tailored features and UI.
+* **Heavily tested from day one.** CKEditor 5 comes with 3x more tests than React itself. All packages have 100% code coverage.
+* **8+ years of support.** It is not yet another framework to be gone next year or a hyped proof-of-concept to fail in a real-life scenario. We have over 15 years of experience in creating rich text editors and invested over 4 years in designing and building your next future-proof rich text editor of choice.
+
+## Documentation
+
+For a general introduction see the [Overview of CKEditor 5 Framework](https://ckeditor.com/docs/ckeditor5/latest/framework/architecture/core-editor-architecture.html) guide and then the [Editing engine architecture guide](https://ckeditor.com/docs/ckeditor5/latest/framework/architecture/editing-engine.html).
+
+Additionally, refer to the [`@ckeditor/ckeditor5-engine` package](https://ckeditor.com/docs/ckeditor5/latest/api/engine.html) page in [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/) for even more information.
+
+## Installation
+
+```bash
+npm install ckeditor5
+```
+
+## License
+
+Licensed under the terms of [GNU General Public License Version 2 or later](http://www.gnu.org/licenses/gpl.html). For full details about the license, please check the `LICENSE.md` file or [https://ckeditor.com/legal/ckeditor-oss-license](https://ckeditor.com/legal/ckeditor-oss-license).

package/dist/controller/datacontroller.d.ts

@@ -0,0 +1,339 @@
+/**
+ * @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-oss-license
+ */
+import Mapper from '../conversion/mapper.js';
+import DowncastDispatcher from '../conversion/downcastdispatcher.js';
+import UpcastDispatcher from '../conversion/upcastdispatcher.js';
+import ViewDocumentFragment from '../view/documentfragment.js';
+import ViewDocument from '../view/document.js';
+import type ViewElement from '../view/element.js';
+import type { StylesProcessor } from '../view/stylesmap.js';
+import type { MatcherPattern } from '../view/matcher.js';
+import type Model from '../model/model.js';
+import type ModelElement from '../model/element.js';
+import type ModelDocumentFragment from '../model/documentfragment.js';
+import type { SchemaContextDefinition } from '../model/schema.js';
+import type { BatchType } from '../model/batch.js';
+import HtmlDataProcessor from '../dataprocessor/htmldataprocessor.js';
+import type DataProcessor from '../dataprocessor/dataprocessor.js';
+declare const DataController_base: {
+    new (): import("@ckeditor/ckeditor5-utils").Emitter;
+    prototype: import("@ckeditor/ckeditor5-utils").Emitter;
+};
+/**
+ * Controller for the data pipeline. The data pipeline controls how data is retrieved from the document
+ * and set inside it. Hence, the controller features two methods which allow to {@link ~DataController#get get}
+ * and {@link ~DataController#set set} data of the {@link ~DataController#model model}
+ * using the given:
+ *
+ * * {@link module:engine/dataprocessor/dataprocessor~DataProcessor data processor},
+ * * downcast converters,
+ * * upcast converters.
+ *
+ * An instance of the data controller is always available in the {@link module:core/editor/editor~Editor#data `editor.data`}
+ * property:
+ *
+ * ```ts
+ * editor.data.get( { rootName: 'customRoot' } ); // -> '<p>Hello!</p>'
+ * ```
+ */
+export default class DataController extends /* #__PURE__ */ DataController_base {
+    /**
+     * Data model.
+     */
+    readonly model: Model;
+    /**
+     * Mapper used for the conversion. It has no permanent bindings, because these are created while getting data and
+     * are cleared directly after the data are converted. However, the mapper is defined as a class property, because
+     * it needs to be passed to the `DowncastDispatcher` as a conversion API.
+     */
+    readonly mapper: Mapper;
+    /**
+     * Downcast dispatcher used by the {@link #get get method}. Downcast converters should be attached to it.
+     */
+    readonly downcastDispatcher: DowncastDispatcher;
+    /**
+     * Upcast dispatcher used by the {@link #set set method}. Upcast converters should be attached to it.
+     */
+    readonly upcastDispatcher: UpcastDispatcher;
+    /**
+     * The view document used by the data controller.
+     */
+    readonly viewDocument: ViewDocument;
+    /**
+     * Styles processor used during the conversion.
+     */
+    readonly stylesProcessor: StylesProcessor;
+    /**
+     * Data processor used specifically for HTML conversion.
+     */
+    readonly htmlProcessor: HtmlDataProcessor;
+    /**
+     * Data processor used during the conversion.
+     * Same instance as {@link #htmlProcessor} by default. Can be replaced at run time to handle different format, e.g. XML or Markdown.
+     */
+    processor: DataProcessor;
+    /**
+     * The view downcast writer just for data conversion purposes, i.e. to modify
+     * the {@link #viewDocument}.
+     */
+    private readonly _viewWriter;
+    /**
+     * Creates a data controller instance.
+     *
+     * @param model Data model.
+     * @param stylesProcessor The styles processor instance.
+     */
+    constructor(model: Model, stylesProcessor: StylesProcessor);
+    /**
+     * Returns the model's data converted by downcast dispatchers attached to {@link #downcastDispatcher} and
+     * formatted by the {@link #processor data processor}.
+     *
+     * A warning is logged when you try to retrieve data for a detached root, as most probably this is a mistake. A detached root should
+     * be treated like it is removed, and you should not save its data. Note, that the detached root data is always an empty string.
+     *
+     * @fires get
+     * @param options Additional configuration for the retrieved data. `DataController` provides two optional
+     * properties: `rootName` and `trim`. Other properties of this object are specified by various editor features.
+     * @param options.rootName Root name. Default 'main'.
+     * @param options.trim Whether returned data should be trimmed. This option is set to `empty` by default,
+     * which means whenever editor content is considered empty, an empty string will be returned. To turn off trimming completely
+     * use `'none'`. In such cases the exact content will be returned (for example a `<p>&nbsp;</p>` for an empty editor).
+     * @returns Output data.
+     */
+    get(options?: {
+        rootName?: string;
+        trim?: 'empty' | 'none';
+        [key: string]: unknown;
+    }): string;
+    /**
+     * Returns the content of the given {@link module:engine/model/element~Element model's element} or
+     * {@link module:engine/model/documentfragment~DocumentFragment model document fragment} converted by the downcast converters
+     * attached to the {@link #downcastDispatcher} and formatted by the {@link #processor data processor}.
+     *
+     * @param modelElementOrFragment The element whose content will be stringified.
+     * @param options Additional configuration passed to the conversion process.
+     * @returns Output data.
+     */
+    stringify(modelElementOrFragment: ModelElement | ModelDocumentFragment, options?: Record<string, unknown>): string;
+    /**
+     * Returns the content of the given {@link module:engine/model/element~Element model element} or
+     * {@link module:engine/model/documentfragment~DocumentFragment model document fragment} converted by the downcast
+     * converters attached to {@link #downcastDispatcher} into a
+     * {@link module:engine/view/documentfragment~DocumentFragment view document fragment}.
+     *
+     * @fires toView
+     * @param modelElementOrFragment Element or document fragment whose content will be converted.
+     * @param options Additional configuration that will be available through the
+     * {@link module:engine/conversion/downcastdispatcher~DowncastConversionApi#options} during the conversion process.
+     * @returns Output view DocumentFragment.
+     */
+    toView(modelElementOrFragment: ModelElement | ModelDocumentFragment, options?: Record<string, unknown>): ViewDocumentFragment;
+    /**
+     * Sets the initial input data parsed by the {@link #processor data processor} and
+     * converted by the {@link #upcastDispatcher view-to-model converters}.
+     * Initial data can be only set to a document whose {@link module:engine/model/document~Document#version} is equal 0.
+     *
+     * **Note** This method is {@link module:utils/observablemixin~Observable#decorate decorated} which is
+     * used by e.g. collaborative editing plugin that syncs remote data on init.
+     *
+     * When data is passed as a string, it is initialized on the default `main` root:
+     *
+     * ```ts
+     * dataController.init( '<p>Foo</p>' ); // Initializes data on the `main` root only, as no other is specified.
+     * ```
+     *
+     * To initialize data on a different root or multiple roots at once, an object containing `rootName` - `data` pairs should be passed:
+     *
+     * ```ts
+     * dataController.init( { main: '<p>Foo</p>', title: '<h1>Bar</h1>' } ); // Initializes data on both the `main` and `title` roots.
+     * ```
+     *
+     * @fires init
+     * @param data Input data as a string or an object containing the `rootName` - `data`
+     * pairs to initialize data on multiple roots at once.
+     * @returns Promise that is resolved after the data is set on the editor.
+     */
+    init(data: string | Record<string, string>): Promise<void>;
+    /**
+     * Sets the input data parsed by the {@link #processor data processor} and
+     * converted by the {@link #upcastDispatcher view-to-model converters}.
+     * This method can be used any time to replace existing editor data with the new one without clearing the
+     * {@link module:engine/model/document~Document#history document history}.
+     *
+     * This method also creates a batch with all the changes applied. If all you need is to parse data, use
+     * the {@link #parse} method.
+     *
+     * When data is passed as a string it is set on the default `main` root:
+     *
+     * ```ts
+     * dataController.set( '<p>Foo</p>' ); // Sets data on the `main` root, as no other is specified.
+     * ```
+     *
+     * To set data on a different root or multiple roots at once, an object containing `rootName` - `data` pairs should be passed:
+     *
+     * ```ts
+     * dataController.set( { main: '<p>Foo</p>', title: '<h1>Bar</h1>' } ); // Sets data on the `main` and `title` roots as specified.
+     * ```
+     *
+     * To set the data with a preserved undo stack and add the change to the undo stack, set `{ isUndoable: true }` as a `batchType` option.
+     *
+     * ```ts
+     * dataController.set( '<p>Foo</p>', { batchType: { isUndoable: true } } );
+     * ```
+     *
+     * @fires set
+     * @param data Input data as a string or an object containing the `rootName` - `data`
+     * pairs to set data on multiple roots at once.
+     * @param options Options for setting data.
+     * @param options.batchType The batch type that will be used to create a batch for the changes applied by this method.
+     * By default, the batch will be set as {@link module:engine/model/batch~Batch#isUndoable not undoable} and the undo stack will be
+     * cleared after the new data is applied (all undo steps will be removed). If the batch type `isUndoable` flag is be set to `true`,
+     * the undo stack will be preserved instead and not cleared when new data is applied.
+     */
+    set(data: string | Record<string, string>, options?: {
+        batchType?: BatchType;
+        [key: string]: unknown;
+    }): void;
+    /**
+     * Returns the data parsed by the {@link #processor data processor} and then converted by upcast converters
+     * attached to the {@link #upcastDispatcher}.
+     *
+     * @see #set
+     * @param data Data to parse.
+     * @param context Base context in which the view will be converted to the model.
+     * See: {@link module:engine/conversion/upcastdispatcher~UpcastDispatcher#convert}.
+     * @returns Parsed data.
+     */
+    parse(data: string, context?: SchemaContextDefinition): ModelDocumentFragment;
+    /**
+     * Returns the result of the given {@link module:engine/view/element~Element view element} or
+     * {@link module:engine/view/documentfragment~DocumentFragment view document fragment} converted by the
+     * {@link #upcastDispatcher view-to-model converters}, wrapped by {@link module:engine/model/documentfragment~DocumentFragment}.
+     *
+     * When marker elements were converted during the conversion process, it will be set as a document fragment's
+     * {@link module:engine/model/documentfragment~DocumentFragment#markers static markers map}.
+     *
+     * @fires toModel
+     * @param viewElementOrFragment The element or document fragment whose content will be converted.
+     * @param context Base context in which the view will be converted to the model.
+     * See: {@link module:engine/conversion/upcastdispatcher~UpcastDispatcher#convert}.
+     * @returns Output document fragment.
+     */
+    toModel(viewElementOrFragment: ViewElement | ViewDocumentFragment, context?: SchemaContextDefinition): ModelDocumentFragment;
+    /**
+     * Adds the style processor normalization rules.
+     *
+     * You can implement your own rules as well as use one of the available processor rules:
+     *
+     * * background: {@link module:engine/view/styles/background~addBackgroundRules}
+     * * border: {@link module:engine/view/styles/border~addBorderRules}
+     * * margin: {@link module:engine/view/styles/margin~addMarginRules}
+     * * padding: {@link module:engine/view/styles/padding~addPaddingRules}
+     */
+    addStyleProcessorRules(callback: (stylesProcessor: StylesProcessor) => void): void;
+    /**
+     * Registers a {@link module:engine/view/matcher~MatcherPattern} on an {@link #htmlProcessor htmlProcessor}
+     * and a {@link #processor processor} for view elements whose content should be treated as raw data
+     * and not processed during the conversion from DOM to view elements.
+     *
+     * The raw data can be later accessed by the {@link module:engine/view/element~Element#getCustomProperty view element custom property}
+     * `"$rawContent"`.
+     *
+     * @param pattern Pattern matching all view elements whose content should be treated as a raw data.
+     */
+    registerRawContentMatcher(pattern: MatcherPattern): void;
+    /**
+     * Removes all event listeners set by the DataController.
+     */
+    destroy(): void;
+    /**
+     * Checks whether all provided root names are actually existing editor roots.
+     *
+     * @param rootNames Root names to check.
+     * @returns Whether all provided root names are existing editor roots.
+     */
+    private _checkIfRootsExists;
+}
+/**
+ * Event fired once the data initialization has finished.
+ *
+ * @eventName ~DataController#ready
+ */
+export type DataControllerReadyEvent = {
+    name: 'ready';
+    args: [];
+};
+/**
+ * An event fired after the {@link ~DataController#init `init()` method} was run. It can be {@link ~DataController#listenTo listened to} in
+ * order to adjust or modify the initialization flow. However, if the `init` event is stopped or prevented,
+ * the {@link ~DataController#event:ready `ready` event} should be fired manually.
+ *
+ * The `init` event is fired by the decorated {@link ~DataController#init} method.
+ * See {@link module:utils/observablemixin~Observable#decorate} for more information and samples.
+ *
+ * @eventName ~DataController#init
+ */
+export type DataControllerInitEvent = {
+    name: 'init';
+    args: [Parameters<DataController['init']>];
+    return: ReturnType<DataController['init']>;
+};
+/**
+ * An event fired after {@link ~DataController#set set() method} has been run.
+ *
+ * The `set` event is fired by the decorated {@link ~DataController#set} method.
+ * See {@link module:utils/observablemixin~Observable#decorate} for more information and samples.
+ *
+ * @eventName ~DataController#set
+ */
+export type DataControllerSetEvent = {
+    name: 'set';
+    args: [Parameters<DataController['set']>];
+    return: ReturnType<DataController['set']>;
+};
+/**
+ * Event fired after the {@link ~DataController#get get() method} has been run.
+ *
+ * The `get` event is fired by the decorated {@link ~DataController#get} method.
+ * See {@link module:utils/observablemixin~Observable#decorate} for more information and samples.
+ *
+ * @eventName ~DataController#get
+ */
+export type DataControllerGetEvent = {
+    name: 'get';
+    args: [Parameters<DataController['get']>];
+    return: ReturnType<DataController['get']>;
+};
+/**
+ * Event fired after the {@link ~DataController#toView toView() method} has been run.
+ *
+ * The `toView` event is fired by the decorated {@link ~DataController#toView} method.
+ * See {@link module:utils/observablemixin~Observable#decorate} for more information and samples.
+ *
+ * @eventName ~DataController#toView
+ */
+export type DataControllerToViewEvent = {
+    name: 'toView';
+    args: [Parameters<DataController['toView']>];
+    return: ReturnType<DataController['toView']>;
+};
+/**
+ * Event fired after the {@link ~DataController#toModel toModel() method} has been run.
+ *
+ * The `toModel` event is fired by the decorated {@link ~DataController#toModel} method.
+ * See {@link module:utils/observablemixin~Observable#decorate} for more information and samples.
+ *
+ * @eventName ~DataController#toModel
+ */
+export type DataControllerToModelEvent = {
+    name: 'toModel';
+    args: [Parameters<DataController['toModel']>];
+    return: ReturnType<DataController['toModel']>;
+};
+export {};

package/dist/controller/editingcontroller.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @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-oss-license
+ */
+import View from '../view/view.js';
+import Mapper from '../conversion/mapper.js';
+import DowncastDispatcher from '../conversion/downcastdispatcher.js';
+import type { default as Model } from '../model/model.js';
+import type ModelItem from '../model/item.js';
+import type { Marker } from '../model/markercollection.js';
+import type { StylesProcessor } from '../view/stylesmap.js';
+declare const EditingController_base: {
+    new (): import("@ckeditor/ckeditor5-utils").Observable;
+    prototype: import("@ckeditor/ckeditor5-utils").Observable;
+};
+/**
+ * A controller for the editing pipeline. The editing pipeline controls the {@link ~EditingController#model model} rendering,
+ * including selection handling. It also creates the {@link ~EditingController#view view} which builds a
+ * browser-independent virtualization over the DOM elements. The editing controller also attaches default converters.
+ */
+export default class EditingController extends /* #__PURE__ */ EditingController_base {
+    /**
+     * Editor model.
+     */
+    readonly model: Model;
+    /**
+     * Editing view controller.
+     */
+    readonly view: View;
+    /**
+     * A mapper that describes the model-view binding.
+     */
+    readonly mapper: Mapper;
+    /**
+     * Downcast dispatcher that converts changes from the model to the {@link #view editing view}.
+     */
+    readonly downcastDispatcher: DowncastDispatcher;
+    /**
+     * Creates an editing controller instance.
+     *
+     * @param model Editing model.
+     * @param stylesProcessor The styles processor instance.
+     */
+    constructor(model: Model, stylesProcessor: StylesProcessor);
+    /**
+     * Removes all event listeners attached to the `EditingController`. Destroys all objects created
+     * by `EditingController` that need to be destroyed.
+     */
+    destroy(): void;
+    /**
+     * Calling this method will refresh the marker by triggering the downcast conversion for it.
+     *
+     * Reconverting the marker is useful when you want to change its {@link module:engine/view/element~Element view element}
+     * without changing any marker data. For instance:
+     *
+     * ```ts
+     * let isCommentActive = false;
+     *
+     * model.conversion.markerToHighlight( {
+     * 	model: 'comment',
+     * 	view: data => {
+     * 		const classes = [ 'comment-marker' ];
+     *
+     * 		if ( isCommentActive ) {
+     * 			classes.push( 'comment-marker--active' );
+     * 		}
+     *
+     * 		return { classes };
+     * 	}
+     * } );
+     *
+     * // ...
+     *
+     * // Change the property that indicates if marker is displayed as active or not.
+     * isCommentActive = true;
+     *
+     * // Reconverting will downcast and synchronize the marker with the new isCommentActive state value.
+     * editor.editing.reconvertMarker( 'comment' );
+     * ```
+     *
+     * **Note**: If you want to reconvert a model item, use {@link #reconvertItem} instead.
+     *
+     * @param markerOrName Name of a marker to update, or a marker instance.
+     */
+    reconvertMarker(markerOrName: Marker | string): void;
+    /**
+     * Calling this method will downcast a model item on demand (by requesting a refresh in the {@link module:engine/model/differ~Differ}).
+     *
+     * You can use it if you want the view representation of a specific item updated as a response to external modifications. For instance,
+     * when the view structure depends not only on the associated model data but also on some external state.
+     *
+     * **Note**: If you want to reconvert a model marker, use {@link #reconvertMarker} instead.
+     *
+     * @param item Item to refresh.
+     */
+    reconvertItem(item: ModelItem): void;
+}
+export {};