@ckeditor/ckeditor5-engine 0.0.0-internal-20241017.0

package/src/dataprocessor/htmldataprocessor.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @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 DomConverter from '../view/domconverter.js';
+import type DataProcessor from './dataprocessor.js';
+import type HtmlWriter from './htmlwriter.js';
+import type ViewDocument from '../view/document.js';
+import type ViewDocumentFragment from '../view/documentfragment.js';
+import type { MatcherPattern } from '../view/matcher.js';
+/**
+ * The HTML data processor class.
+ * This data processor implementation uses HTML as input and output data.
+ */
+export default class HtmlDataProcessor implements DataProcessor {
+    /**
+     * A DOM parser instance used to parse an HTML string to an HTML document.
+     */
+    domParser: DOMParser;
+    /**
+     * A DOM converter used to convert DOM elements to view elements.
+     */
+    domConverter: DomConverter;
+    /**
+     * A basic HTML writer instance used to convert DOM elements to an HTML string.
+     */
+    htmlWriter: HtmlWriter;
+    skipComments: boolean;
+    /**
+     * Creates a new instance of the HTML data processor class.
+     *
+     * @param document The view document instance.
+     */
+    constructor(document: ViewDocument);
+    /**
+     * Converts a provided {@link module:engine/view/documentfragment~DocumentFragment document fragment}
+     * to data format – in this case to an HTML string.
+     *
+     * @returns HTML string.
+     */
+    toData(viewFragment: ViewDocumentFragment): string;
+    /**
+     * Converts the provided HTML string to a view tree.
+     *
+     * @param data An HTML string.
+     * @returns A converted view element.
+     */
+    toView(data: string): ViewDocumentFragment;
+    /**
+     * Registers a {@link module:engine/view/matcher~MatcherPattern} for view elements whose content should be treated as raw data
+     * and not processed during the conversion from the DOM to the view elements.
+     *
+     * The raw data can be later accessed by a
+     * {@link module:engine/view/element~Element#getCustomProperty custom property of a view element} called `"$rawContent"`.
+     *
+     * @param pattern Pattern matching all view elements whose content should be treated as raw data.
+     */
+    registerRawContentMatcher(pattern: MatcherPattern): void;
+    /**
+     * If the processor is set to use marked fillers, it will insert `&nbsp;` fillers wrapped in `<span>` elements
+     * (`<span data-cke-filler="true">&nbsp;</span>`) instead of regular `&nbsp;` characters.
+     *
+     * This mode allows for a more precise handling of the block fillers (so they do not leak into the editor content) but
+     * bloats the editor data with additional markup.
+     *
+     * This mode may be required by some features and will be turned on by them automatically.
+     *
+     * @param type Whether to use the default or the marked `&nbsp;` block fillers.
+     */
+    useFillerType(type: 'default' | 'marked'): void;
+    /**
+     * Converts an HTML string to its DOM representation. Returns a document fragment containing nodes parsed from
+     * the provided data.
+     */
+    protected _toDom(data: string): DocumentFragment;
+}

package/src/dataprocessor/htmldataprocessor.js

@@ -0,0 +1,96 @@
+/**
+ * @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/dataprocessor/htmldataprocessor
+ */
+/* globals DOMParser */
+import BasicHtmlWriter from './basichtmlwriter.js';
+import DomConverter from '../view/domconverter.js';
+/**
+ * The HTML data processor class.
+ * This data processor implementation uses HTML as input and output data.
+ */
+export default class HtmlDataProcessor {
+    /**
+     * Creates a new instance of the HTML data processor class.
+     *
+     * @param document The view document instance.
+     */
+    constructor(document) {
+        this.skipComments = true;
+        this.domParser = new DOMParser();
+        this.domConverter = new DomConverter(document, { renderingMode: 'data' });
+        this.htmlWriter = new BasicHtmlWriter();
+    }
+    /**
+     * Converts a provided {@link module:engine/view/documentfragment~DocumentFragment document fragment}
+     * to data format – in this case to an HTML string.
+     *
+     * @returns HTML string.
+     */
+    toData(viewFragment) {
+        // Convert view DocumentFragment to DOM DocumentFragment.
+        const domFragment = this.domConverter.viewToDom(viewFragment);
+        // Convert DOM DocumentFragment to HTML output.
+        return this.htmlWriter.getHtml(domFragment);
+    }
+    /**
+     * Converts the provided HTML string to a view tree.
+     *
+     * @param data An HTML string.
+     * @returns A converted view element.
+     */
+    toView(data) {
+        // Convert input HTML data to DOM DocumentFragment.
+        const domFragment = this._toDom(data);
+        // Convert DOM DocumentFragment to view DocumentFragment.
+        return this.domConverter.domToView(domFragment, { skipComments: this.skipComments });
+    }
+    /**
+     * Registers a {@link module:engine/view/matcher~MatcherPattern} for view elements whose content should be treated as raw data
+     * and not processed during the conversion from the DOM to the view elements.
+     *
+     * The raw data can be later accessed by a
+     * {@link module:engine/view/element~Element#getCustomProperty custom property of a view element} called `"$rawContent"`.
+     *
+     * @param pattern Pattern matching all view elements whose content should be treated as raw data.
+     */
+    registerRawContentMatcher(pattern) {
+        this.domConverter.registerRawContentMatcher(pattern);
+    }
+    /**
+     * If the processor is set to use marked fillers, it will insert `&nbsp;` fillers wrapped in `<span>` elements
+     * (`<span data-cke-filler="true">&nbsp;</span>`) instead of regular `&nbsp;` characters.
+     *
+     * This mode allows for a more precise handling of the block fillers (so they do not leak into the editor content) but
+     * bloats the editor data with additional markup.
+     *
+     * This mode may be required by some features and will be turned on by them automatically.
+     *
+     * @param type Whether to use the default or the marked `&nbsp;` block fillers.
+     */
+    useFillerType(type) {
+        this.domConverter.blockFillerMode = type == 'marked' ? 'markedNbsp' : 'nbsp';
+    }
+    /**
+     * Converts an HTML string to its DOM representation. Returns a document fragment containing nodes parsed from
+     * the provided data.
+     */
+    _toDom(data) {
+        // Wrap data with a <body> tag so leading non-layout nodes (like <script>, <style>, HTML comment)
+        // will be preserved in the body collection.
+        // Do it only for data that is not a full HTML document.
+        if (!/<(?:html|body|head|meta)(?:\s[^>]*)?>/i.test(data.trim().slice(0, 10000))) {
+            data = `<body>${data}</body>`;
+        }
+        const document = this.domParser.parseFromString(data, 'text/html');
+        const fragment = document.createDocumentFragment();
+        const bodyChildNodes = document.body.childNodes;
+        while (bodyChildNodes.length > 0) {
+            fragment.appendChild(bodyChildNodes[0]);
+        }
+        return fragment;
+    }
+}

package/src/dataprocessor/htmlwriter.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @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/dataprocessor/htmlwriter
+ */
+/**
+ * The HTML writer interface.
+ */
+export default interface HtmlWriter {
+    /**
+     * Returns an HTML string created from a document fragment.
+     */
+    getHtml(fragment: DocumentFragment): string;
+}

package/src/dataprocessor/htmlwriter.js

@@ -0,0 +1,5 @@
+/**
+ * @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
+ */
+export {};

package/src/dataprocessor/xmldataprocessor.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @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 DomConverter from '../view/domconverter.js';
+import type DataProcessor from './dataprocessor.js';
+import type HtmlWriter from './htmlwriter.js';
+import type ViewDocument from '../view/document.js';
+import type ViewDocumentFragment from '../view/documentfragment.js';
+import type { MatcherPattern } from '../view/matcher.js';
+/**
+ * The XML data processor class.
+ * This data processor implementation uses XML as input and output data.
+ * This class is needed because unlike HTML, XML allows to use any tag with any value.
+ * For example, `<link>Text</link>` is a valid XML but invalid HTML.
+ */
+export default class XmlDataProcessor implements DataProcessor {
+    /**
+     * A list of namespaces allowed to use in the XML input.
+     *
+     * For example, registering namespaces [ 'attribute', 'container' ] allows to use `<attirbute:tagName></attribute:tagName>`
+     * and `<container:tagName></container:tagName>` input. It is mainly for debugging.
+     */
+    namespaces: Array<string>;
+    /**
+     * DOM parser instance used to parse an XML string to an XML document.
+     */
+    domParser: DOMParser;
+    /**
+     * DOM converter used to convert DOM elements to view elements.
+     */
+    domConverter: DomConverter;
+    /**
+     * A basic HTML writer instance used to convert DOM elements to an XML string.
+     * There is no need to use a dedicated XML writer because the basic HTML writer works well in this case.
+     */
+    htmlWriter: HtmlWriter;
+    skipComments: boolean;
+    /**
+     * Creates a new instance of the XML data processor class.
+     *
+     * @param document The view document instance.
+     * @param options Configuration options.
+     * @param options.namespaces A list of namespaces allowed to use in the XML input.
+     */
+    constructor(document: ViewDocument, options?: {
+        namespaces?: Array<string>;
+    });
+    /**
+     * Converts the provided {@link module:engine/view/documentfragment~DocumentFragment document fragment}
+     * to data format &ndash; in this case an XML string.
+     *
+     * @returns An XML string.
+     */
+    toData(viewFragment: ViewDocumentFragment): string;
+    /**
+     * Converts the provided XML string to a view tree.
+     *
+     * @param data An XML string.
+     * @returns A converted view element.
+     */
+    toView(data: string): ViewDocumentFragment;
+    /**
+     * Registers a {@link module:engine/view/matcher~MatcherPattern} for view elements whose content should be treated as raw data
+     * and not processed during the conversion from XML to view elements.
+     *
+     * The raw data can be later accessed by a
+     * {@link module:engine/view/element~Element#getCustomProperty custom property of a view element} called `"$rawContent"`.
+     *
+     * @param pattern Pattern matching all view elements whose content should be treated as raw data.
+     */
+    registerRawContentMatcher(pattern: MatcherPattern): void;
+    /**
+     * If the processor is set to use marked fillers, it will insert `&nbsp;` fillers wrapped in `<span>` elements
+     * (`<span data-cke-filler="true">&nbsp;</span>`) instead of regular `&nbsp;` characters.
+     *
+     * This mode allows for a more precise handling of block fillers (so they do not leak into editor content) but
+     * bloats the editor data with additional markup.
+     *
+     * This mode may be required by some features and will be turned on by them automatically.
+     *
+     * @param type Whether to use the default or the marked `&nbsp;` block fillers.
+     */
+    useFillerType(type: 'default' | 'marked'): void;
+    /**
+     * Converts an XML string to its DOM representation. Returns a document fragment containing nodes parsed from
+     * the provided data.
+     */
+    private _toDom;
+}

package/src/dataprocessor/xmldataprocessor.js

@@ -0,0 +1,108 @@
+/**
+ * @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/dataprocessor/xmldataprocessor
+ */
+/* globals DOMParser */
+import BasicHtmlWriter from './basichtmlwriter.js';
+import DomConverter from '../view/domconverter.js';
+/**
+ * The XML data processor class.
+ * This data processor implementation uses XML as input and output data.
+ * This class is needed because unlike HTML, XML allows to use any tag with any value.
+ * For example, `<link>Text</link>` is a valid XML but invalid HTML.
+ */
+export default class XmlDataProcessor {
+    /**
+     * Creates a new instance of the XML data processor class.
+     *
+     * @param document The view document instance.
+     * @param options Configuration options.
+     * @param options.namespaces A list of namespaces allowed to use in the XML input.
+     */
+    constructor(document, options = {}) {
+        this.skipComments = true;
+        this.namespaces = options.namespaces || [];
+        this.domParser = new DOMParser();
+        this.domConverter = new DomConverter(document, { renderingMode: 'data' });
+        this.htmlWriter = new BasicHtmlWriter();
+    }
+    /**
+     * Converts the provided {@link module:engine/view/documentfragment~DocumentFragment document fragment}
+     * to data format &ndash; in this case an XML string.
+     *
+     * @returns An XML string.
+     */
+    toData(viewFragment) {
+        // Convert view DocumentFragment to DOM DocumentFragment.
+        const domFragment = this.domConverter.viewToDom(viewFragment);
+        // Convert DOM DocumentFragment to XML output.
+        // There is no need to use dedicated for XML serializing method because BasicHtmlWriter works well in this case.
+        return this.htmlWriter.getHtml(domFragment);
+    }
+    /**
+     * Converts the provided XML string to a view tree.
+     *
+     * @param data An XML string.
+     * @returns A converted view element.
+     */
+    toView(data) {
+        // Convert input XML data to DOM DocumentFragment.
+        const domFragment = this._toDom(data);
+        // Convert DOM DocumentFragment to view DocumentFragment.
+        return this.domConverter.domToView(domFragment, {
+            keepOriginalCase: true,
+            skipComments: this.skipComments
+        });
+    }
+    /**
+     * Registers a {@link module:engine/view/matcher~MatcherPattern} for view elements whose content should be treated as raw data
+     * and not processed during the conversion from XML to view elements.
+     *
+     * The raw data can be later accessed by a
+     * {@link module:engine/view/element~Element#getCustomProperty custom property of a view element} called `"$rawContent"`.
+     *
+     * @param pattern Pattern matching all view elements whose content should be treated as raw data.
+     */
+    registerRawContentMatcher(pattern) {
+        this.domConverter.registerRawContentMatcher(pattern);
+    }
+    /**
+     * If the processor is set to use marked fillers, it will insert `&nbsp;` fillers wrapped in `<span>` elements
+     * (`<span data-cke-filler="true">&nbsp;</span>`) instead of regular `&nbsp;` characters.
+     *
+     * This mode allows for a more precise handling of block fillers (so they do not leak into editor content) but
+     * bloats the editor data with additional markup.
+     *
+     * This mode may be required by some features and will be turned on by them automatically.
+     *
+     * @param type Whether to use the default or the marked `&nbsp;` block fillers.
+     */
+    useFillerType(type) {
+        this.domConverter.blockFillerMode = type == 'marked' ? 'markedNbsp' : 'nbsp';
+    }
+    /**
+     * Converts an XML string to its DOM representation. Returns a document fragment containing nodes parsed from
+     * the provided data.
+     */
+    _toDom(data) {
+        // Stringify namespaces.
+        const namespaces = this.namespaces.map(nsp => `xmlns:${nsp}="nsp"`).join(' ');
+        // Wrap data into root element with optional namespace definitions.
+        data = `<xml ${namespaces}>${data}</xml>`;
+        const parsedDocument = this.domParser.parseFromString(data, 'text/xml');
+        // Parse validation.
+        const parserError = parsedDocument.querySelector('parsererror');
+        if (parserError) {
+            throw new Error('Parse error - ' + parserError.textContent);
+        }
+        const fragment = parsedDocument.createDocumentFragment();
+        const nodes = parsedDocument.documentElement.childNodes;
+        while (nodes.length > 0) {
+            fragment.appendChild(nodes[0]);
+        }
+        return fragment;
+    }
+}

package/src/dev-utils/model.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @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 Model from '../model/model.js';
+import ModelRange from '../model/range.js';
+import ModelPosition from '../model/position.js';
+import ModelSelection from '../model/selection.js';
+import ModelDocumentFragment from '../model/documentfragment.js';
+import DocumentSelection from '../model/documentselection.js';
+import type { BatchType } from '../model/batch.js';
+import type MarkerCollection from '../model/markercollection.js';
+import type { default as Schema, SchemaContextDefinition } from '../model/schema.js';
+import type ModelNode from '../model/node.js';
+/**
+ * Writes the content of a model {@link module:engine/model/document~Document document} to an HTML-like string.
+ *
+ * ```ts
+ * getData( editor.model ); // -> '<paragraph>Foo![]</paragraph>'
+ * ```
+ *
+ * **Note:** A {@link module:engine/model/text~Text text} node that contains attributes will be represented as:
+ *
+ * ```xml
+ * <$text attribute="value">Text data</$text>
+ * ```
+ *
+ * **Note:** Using this tool in production-grade code is not recommended. It was designed for development, prototyping,
+ * debugging and testing.
+ *
+ * @param options.withoutSelection Whether to write the selection. When set to `true`, the selection will
+ * not be included in the returned string.
+ * @param options.rootName The name of the root from which the data should be stringified. If not provided,
+ * the default `main` name will be used.
+ * @param options.convertMarkers Whether to include markers in the returned string.
+ * @returns The stringified data.
+ */
+export declare function getData(model: Model, options?: {
+    withoutSelection?: boolean;
+    rootName?: string;
+    convertMarkers?: boolean;
+}): string;
+export declare namespace getData {
+    var _stringify: typeof stringify;
+}
+/**
+ * Sets the content of a model {@link module:engine/model/document~Document document} provided as an HTML-like string.
+ *
+ * ```ts
+ * setData( editor.model, '<paragraph>Foo![]</paragraph>' );
+ * ```
+ *
+ * **Note:** Remember to register elements in the {@link module:engine/model/model~Model#schema model's schema} before
+ * trying to use them.
+ *
+ * **Note:** To create a {@link module:engine/model/text~Text text} node that contains attributes use:
+ *
+ * ```xml
+ * <$text attribute="value">Text data</$text>
+ * ```
+ *
+ * **Note:** Using this tool in production-grade code is not recommended. It was designed for development, prototyping,
+ * debugging and testing.
+ *
+ * @param data HTML-like string to write into the document.
+ * @param options.rootName Root name where parsed data will be stored. If not provided, the default `main`
+ * name will be used.
+ * @param options.selectionAttributes A list of attributes which will be passed to the selection.
+ * @param options.lastRangeBackward If set to `true`, the last range will be added as backward.
+ * @param options.batchType Batch type used for inserting elements. See {@link module:engine/model/batch~Batch#constructor}.
+ * See {@link module:engine/model/batch~Batch#type}.
+ */
+export declare function setData(model: Model, data: string, options?: {
+    rootName?: string;
+    selectionAttributes?: Record<string, unknown>;
+    lastRangeBackward?: boolean;
+    batchType?: BatchType;
+    inlineObjectElements?: Array<string>;
+}): void;
+export declare namespace setData {
+    var _parse: typeof parse;
+}
+/**
+ * Converts model nodes to HTML-like string representation.
+ *
+ * **Note:** A {@link module:engine/model/text~Text text} node that contains attributes will be represented as:
+ *
+ * ```xml
+ * <$text attribute="value">Text data</$text>
+ * ```
+ *
+ * @param node A node to stringify.
+ * @param selectionOrPositionOrRange A selection instance whose ranges will be included in the returned string data.
+ * If a range instance is provided, it will be converted to a selection containing this range. If a position instance
+ * is provided, it will be converted to a selection containing one range collapsed at this position.
+ * @param markers Markers to include.
+ * @returns An HTML-like string representing the model.
+ */
+export declare function stringify(node: ModelNode | ModelDocumentFragment, selectionOrPositionOrRange?: ModelSelection | DocumentSelection | ModelPosition | ModelRange | null, markers?: MarkerCollection | null): string;
+/**
+ * Parses an HTML-like string and returns the model {@link module:engine/model/rootelement~RootElement rootElement}.
+ *
+ * **Note:** To create a {@link module:engine/model/text~Text text} node that contains attributes use:
+ *
+ * ```xml
+ * <$text attribute="value">Text data</$text>
+ * ```
+ *
+ * @param data HTML-like string to be parsed.
+ * @param schema A schema instance used by converters for element validation.
+ * @param options Additional configuration.
+ * @param options.selectionAttributes A list of attributes which will be passed to the selection.
+ * @param options.lastRangeBackward If set to `true`, the last range will be added as backward.
+ * @param options.context The conversion context. If not provided, the default `'$root'` will be used.
+ * @returns Returns the parsed model node or an object with two fields: `model` and `selection`,
+ * when selection ranges were included in the data to parse.
+ */
+export declare function parse(data: string, schema: Schema, options?: {
+    selectionAttributes?: Record<string, unknown> | Iterable<[string, unknown]>;
+    lastRangeBackward?: boolean;
+    context?: SchemaContextDefinition;
+    inlineObjectElements?: Array<string>;
+}): ModelNode | ModelDocumentFragment | {
+    model: ModelNode | ModelDocumentFragment;
+    selection: ModelSelection;
+};