@ckeditor/ckeditor5-html-support 0.0.0-internal-20241017.0

package/src/dataschema.d.ts

@@ -0,0 +1,187 @@
+/**
+ * @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 html-support/dataschema
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import type { AttributeProperties, SchemaItemDefinition } from 'ckeditor5/src/engine.js';
+/**
+ * Holds representation of the extended HTML document type definitions to be used by the
+ * editor in HTML support.
+ *
+ * Data schema is represented by data schema definitions.
+ *
+ * To add new definition for block element,
+ * use {@link module:html-support/dataschema~DataSchema#registerBlockElement} method:
+ *
+ * ```ts
+ * dataSchema.registerBlockElement( {
+ * 	view: 'section',
+ * 	model: 'my-section',
+ * 	modelSchema: {
+ * 		inheritAllFrom: '$block'
+ * 	}
+ * } );
+ * ```
+ *
+ * To add new definition for inline element,
+ * use {@link module:html-support/dataschema~DataSchema#registerInlineElement} method:
+ *
+ * ```
+ * dataSchema.registerInlineElement( {
+ * 	view: 'span',
+ * 	model: 'my-span',
+ * 	attributeProperties: {
+ * 		copyOnEnter: true
+ * 	}
+ * } );
+ * ```
+ */
+export default class DataSchema extends Plugin {
+    /**
+     * A map of registered data schema definitions.
+     */
+    private readonly _definitions;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "DataSchema";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Add new data schema definition describing block element.
+     */
+    registerBlockElement(definition: DataSchemaBlockElementDefinition): void;
+    /**
+     * Add new data schema definition describing inline element.
+     */
+    registerInlineElement(definition: DataSchemaInlineElementDefinition): void;
+    /**
+     * Updates schema definition describing block element with new properties.
+     *
+     * Creates new scheme if it doesn't exist.
+     * Array properties are concatenated with original values.
+     *
+     * @param definition Definition update.
+     */
+    extendBlockElement(definition: DataSchemaBlockElementDefinition): void;
+    /**
+     * Updates schema definition describing inline element with new properties.
+     *
+     * Creates new scheme if it doesn't exist.
+     * Array properties are concatenated with original values.
+     *
+     * @param definition Definition update.
+     */
+    extendInlineElement(definition: DataSchemaInlineElementDefinition): void;
+    /**
+     * Returns all definitions matching the given view name.
+     *
+     * @param includeReferences Indicates if this method should also include definitions of referenced models.
+     */
+    getDefinitionsForView(viewName: string | RegExp, includeReferences?: boolean): Set<DataSchemaDefinition>;
+    /**
+     * Returns definitions matching the given model name.
+     */
+    getDefinitionsForModel(modelName: string): Array<DataSchemaDefinition>;
+    /**
+     * Returns definitions matching the given view name.
+     */
+    private _getMatchingViewDefinitions;
+    /**
+     * Resolves all definition references registered for the given data schema definition.
+     *
+     * @param modelName Data schema model name.
+     */
+    private _getReferences;
+    /**
+     * Updates schema definition with new properties.
+     *
+     * Creates new scheme if it doesn't exist.
+     * Array properties are concatenated with original values.
+     *
+     * @param definition Definition update.
+     */
+    private _extendDefinition;
+}
+/**
+ * A base definition of {@link module:html-support/dataschema~DataSchema data schema}.
+ */
+export interface DataSchemaDefinition {
+    /**
+     * Name of the model.
+     */
+    model: string;
+    /**
+     * Name of the view element.
+     */
+    view?: string;
+    /**
+     * Indicates that the definition describes object element.
+     */
+    isObject?: boolean;
+    /**
+     * The model schema item definition describing registered model.
+     */
+    modelSchema?: SchemaItemDefinition;
+    /**
+     * Indicates that the definition describes block element.
+     * Set by {@link module:html-support/dataschema~DataSchema#registerBlockElement} method.
+     */
+    isBlock?: boolean;
+    /**
+     * Indicates that the definition describes inline element.
+     */
+    isInline?: boolean;
+}
+/**
+ * A definition of {@link module:html-support/dataschema~DataSchema data schema} for block elements.
+ */
+export interface DataSchemaBlockElementDefinition extends DataSchemaDefinition {
+    /**
+     * Should be used when an element can behave both as a sectioning element (e.g. article) and
+     * element accepting only inline content (e.g. paragraph).
+     * If an element contains only inline content, this option will be used as a model name.
+     */
+    paragraphLikeModel?: string;
+}
+/**
+ * A definition of {@link module:html-support/dataschema~DataSchema data schema} for inline elements.
+ */
+export interface DataSchemaInlineElementDefinition extends DataSchemaDefinition {
+    /**
+     *  Additional metadata describing the model attribute.
+     */
+    attributeProperties?: AttributeProperties;
+    /**
+     * Element priority. Decides in what order elements are wrapped by
+     * {@link module:engine/view/downcastwriter~DowncastWriter}.
+     * Set by {@link module:html-support/dataschema~DataSchema#registerInlineElement} method.
+     */
+    priority?: number;
+    /**
+     * The name of the model attribute that generates the same view element. GHS inline attribute
+     * will be removed from the model tree as soon as the coupled attribute is removed. See
+     * {@link module:html-support/datafilter~DataFilter#_registerCoupledAttributesPostFixer GHS post-fixer} for more details.
+     */
+    coupledAttribute?: string;
+    /**
+     * Indicates that element should not be converted as a model text attribute.
+     * It is used to map view elements that do not have a separate model element but their data is stored in a model attribute.
+     * For example `<tbody>` element does not have a dedicated model element and GHS stores attributes of `<tbody>`
+     * in the `htmlTbodyAttributes` model attribute of the `table` model element.
+     */
+    appliesToBlock?: boolean | string;
+    /**
+     * Indicates that an element should be preserved even if it has no content.
+     */
+    allowEmpty?: boolean;
+}

package/src/dataschema.js

@@ -0,0 +1,202 @@
+/**
+ * @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 html-support/dataschema
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import { toArray } from 'ckeditor5/src/utils.js';
+import defaultConfig from './schemadefinitions.js';
+import { mergeWith } from 'lodash-es';
+/**
+ * Holds representation of the extended HTML document type definitions to be used by the
+ * editor in HTML support.
+ *
+ * Data schema is represented by data schema definitions.
+ *
+ * To add new definition for block element,
+ * use {@link module:html-support/dataschema~DataSchema#registerBlockElement} method:
+ *
+ * ```ts
+ * dataSchema.registerBlockElement( {
+ * 	view: 'section',
+ * 	model: 'my-section',
+ * 	modelSchema: {
+ * 		inheritAllFrom: '$block'
+ * 	}
+ * } );
+ * ```
+ *
+ * To add new definition for inline element,
+ * use {@link module:html-support/dataschema~DataSchema#registerInlineElement} method:
+ *
+ * ```
+ * dataSchema.registerInlineElement( {
+ * 	view: 'span',
+ * 	model: 'my-span',
+ * 	attributeProperties: {
+ * 		copyOnEnter: true
+ * 	}
+ * } );
+ * ```
+ */
+export default class DataSchema extends Plugin {
+    constructor() {
+        super(...arguments);
+        /**
+         * A map of registered data schema definitions.
+         */
+        this._definitions = [];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'DataSchema';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        for (const definition of defaultConfig.block) {
+            this.registerBlockElement(definition);
+        }
+        for (const definition of defaultConfig.inline) {
+            this.registerInlineElement(definition);
+        }
+    }
+    /**
+     * Add new data schema definition describing block element.
+     */
+    registerBlockElement(definition) {
+        this._definitions.push({ ...definition, isBlock: true });
+    }
+    /**
+     * Add new data schema definition describing inline element.
+     */
+    registerInlineElement(definition) {
+        this._definitions.push({ ...definition, isInline: true });
+    }
+    /**
+     * Updates schema definition describing block element with new properties.
+     *
+     * Creates new scheme if it doesn't exist.
+     * Array properties are concatenated with original values.
+     *
+     * @param definition Definition update.
+     */
+    extendBlockElement(definition) {
+        this._extendDefinition({ ...definition, isBlock: true });
+    }
+    /**
+     * Updates schema definition describing inline element with new properties.
+     *
+     * Creates new scheme if it doesn't exist.
+     * Array properties are concatenated with original values.
+     *
+     * @param definition Definition update.
+     */
+    extendInlineElement(definition) {
+        this._extendDefinition({ ...definition, isInline: true });
+    }
+    /**
+     * Returns all definitions matching the given view name.
+     *
+     * @param includeReferences Indicates if this method should also include definitions of referenced models.
+     */
+    getDefinitionsForView(viewName, includeReferences = false) {
+        const definitions = new Set();
+        for (const definition of this._getMatchingViewDefinitions(viewName)) {
+            if (includeReferences) {
+                for (const reference of this._getReferences(definition.model)) {
+                    definitions.add(reference);
+                }
+            }
+            definitions.add(definition);
+        }
+        return definitions;
+    }
+    /**
+     * Returns definitions matching the given model name.
+     */
+    getDefinitionsForModel(modelName) {
+        return this._definitions.filter(definition => definition.model == modelName);
+    }
+    /**
+     * Returns definitions matching the given view name.
+     */
+    _getMatchingViewDefinitions(viewName) {
+        return this._definitions.filter(def => def.view && testViewName(viewName, def.view));
+    }
+    /**
+     * Resolves all definition references registered for the given data schema definition.
+     *
+     * @param modelName Data schema model name.
+     */
+    *_getReferences(modelName) {
+        const inheritProperties = [
+            'inheritAllFrom',
+            'inheritTypesFrom',
+            'allowWhere',
+            'allowContentOf',
+            'allowAttributesOf'
+        ];
+        const definitions = this._definitions.filter(definition => definition.model == modelName);
+        for (const { modelSchema } of definitions) {
+            if (!modelSchema) {
+                continue;
+            }
+            for (const property of inheritProperties) {
+                for (const referenceName of toArray(modelSchema[property] || [])) {
+                    const definitions = this._definitions.filter(definition => definition.model == referenceName);
+                    for (const definition of definitions) {
+                        if (referenceName !== modelName) {
+                            yield* this._getReferences(definition.model);
+                            yield definition;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Updates schema definition with new properties.
+     *
+     * Creates new scheme if it doesn't exist.
+     * Array properties are concatenated with original values.
+     *
+     * @param definition Definition update.
+     */
+    _extendDefinition(definition) {
+        const currentDefinitions = Array.from(this._definitions.entries())
+            .filter(([, currentDefinition]) => currentDefinition.model == definition.model);
+        if (currentDefinitions.length == 0) {
+            this._definitions.push(definition);
+            return;
+        }
+        for (const [idx, currentDefinition] of currentDefinitions) {
+            this._definitions[idx] = mergeWith({}, currentDefinition, definition, (target, source) => {
+                return Array.isArray(target) ? target.concat(source) : undefined;
+            });
+        }
+    }
+}
+/**
+ * Test view name against the given pattern.
+ */
+function testViewName(pattern, viewName) {
+    if (typeof pattern === 'string') {
+        return pattern === viewName;
+    }
+    if (pattern instanceof RegExp) {
+        return pattern.test(viewName);
+    }
+    return false;
+}

package/src/fullpage.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @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 html-support/fullpage
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+/**
+ * The full page editing feature. It preserves the whole HTML page in the editor data.
+ */
+export default class FullPage extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "FullPage";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/src/fullpage.js

@@ -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 html-support/fullpage
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import { UpcastWriter } from 'ckeditor5/src/engine.js';
+import HtmlPageDataProcessor from './htmlpagedataprocessor.js';
+/**
+ * The full page editing feature. It preserves the whole HTML page in the editor data.
+ */
+export default class FullPage extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'FullPage';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        const properties = ['$fullPageDocument', '$fullPageDocType', '$fullPageXmlDeclaration'];
+        editor.data.processor = new HtmlPageDataProcessor(editor.data.viewDocument);
+        editor.model.schema.extend('$root', {
+            allowAttributes: properties
+        });
+        // Apply custom properties from view document fragment to the model root attributes.
+        editor.data.on('toModel', (evt, [viewElementOrFragment]) => {
+            const root = editor.model.document.getRoot();
+            editor.model.change(writer => {
+                for (const name of properties) {
+                    const value = viewElementOrFragment.getCustomProperty(name);
+                    if (value) {
+                        writer.setAttribute(name, value, root);
+                    }
+                }
+            });
+        }, { priority: 'low' });
+        // Apply root attributes to the view document fragment.
+        editor.data.on('toView', (evt, [modelElementOrFragment]) => {
+            if (!modelElementOrFragment.is('rootElement')) {
+                return;
+            }
+            const root = modelElementOrFragment;
+            const viewFragment = evt.return;
+            if (!root.hasAttribute('$fullPageDocument')) {
+                return;
+            }
+            const writer = new UpcastWriter(viewFragment.document);
+            for (const name of properties) {
+                const value = root.getAttribute(name);
+                if (value) {
+                    writer.setCustomProperty(name, value, viewFragment);
+                }
+            }
+        }, { priority: 'low' });
+        // Clear root attributes related to full page editing on editor content reset.
+        editor.data.on('set', () => {
+            const root = editor.model.document.getRoot();
+            editor.model.change(writer => {
+                for (const name of properties) {
+                    if (root.hasAttribute(name)) {
+                        writer.removeAttribute(name, root);
+                    }
+                }
+            });
+        }, { priority: 'high' });
+        // Make sure that document is returned even if there is no content in the page body.
+        editor.data.on('get', (evt, args) => {
+            if (!args[0]) {
+                args[0] = {};
+            }
+            args[0].trim = false;
+        }, { priority: 'high' });
+    }
+}

package/src/generalhtmlsupport.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
+ */
+/**
+ * @module html-support/generalhtmlsupport
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import { type ArrayOrItem } from 'ckeditor5/src/utils.js';
+import DataFilter from './datafilter.js';
+import CodeBlockElementSupport from './integrations/codeblock.js';
+import DualContentModelElementSupport from './integrations/dualcontent.js';
+import HeadingElementSupport from './integrations/heading.js';
+import ImageElementSupport from './integrations/image.js';
+import MediaEmbedElementSupport from './integrations/mediaembed.js';
+import ScriptElementSupport from './integrations/script.js';
+import TableElementSupport from './integrations/table.js';
+import StyleElementSupport from './integrations/style.js';
+import ListElementSupport from './integrations/list.js';
+import CustomElementSupport from './integrations/customelement.js';
+import type { Selectable } from 'ckeditor5/src/engine.js';
+/**
+ * The General HTML Support feature.
+ *
+ * This is a "glue" plugin which initializes the {@link module:html-support/datafilter~DataFilter data filter} configuration
+ * and features integration with the General HTML Support.
+ */
+export default class GeneralHtmlSupport extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "GeneralHtmlSupport";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof DataFilter, typeof CodeBlockElementSupport, typeof DualContentModelElementSupport, typeof HeadingElementSupport, typeof ImageElementSupport, typeof MediaEmbedElementSupport, typeof ScriptElementSupport, typeof TableElementSupport, typeof StyleElementSupport, typeof ListElementSupport, typeof CustomElementSupport];
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Returns a GHS model attribute name related to a given view element name.
+     *
+     * @internal
+     * @param viewElementName A view element name.
+     */
+    getGhsAttributeNameForElement(viewElementName: string): string;
+    /**
+     * Updates GHS model attribute for a specified view element name, so it includes the given class name.
+     *
+     * @internal
+     * @param viewElementName A view element name.
+     * @param className The css class to add.
+     * @param selectable The selection or element to update.
+     */
+    addModelHtmlClass(viewElementName: string, className: ArrayOrItem<string>, selectable: Selectable): void;
+    /**
+     * Updates GHS model attribute for a specified view element name, so it does not include the given class name.
+     *
+     * @internal
+     * @param viewElementName A view element name.
+     * @param className The css class to remove.
+     * @param selectable The selection or element to update.
+     */
+    removeModelHtmlClass(viewElementName: string, className: ArrayOrItem<string>, selectable: Selectable): void;
+    /**
+     * Updates GHS model attribute for a specified view element name, so it includes the given attribute.
+     *
+     * @param viewElementName A view element name.
+     * @param attributes The object with attributes to set.
+     * @param selectable The selection or element to update.
+     */
+    private setModelHtmlAttributes;
+    /**
+     * Updates GHS model attribute for a specified view element name, so it does not include the given attribute.
+     *
+     * @param viewElementName A view element name.
+     * @param attributeName The attribute name (or names) to remove.
+     * @param selectable The selection or element to update.
+     */
+    private removeModelHtmlAttributes;
+    /**
+     * Updates GHS model attribute for a specified view element name, so it includes a given style.
+     *
+     * @param viewElementName A view element name.
+     * @param styles The object with styles to set.
+     * @param selectable The selection or element to update.
+     */
+    private setModelHtmlStyles;
+    /**
+     * Updates GHS model attribute for a specified view element name, so it does not include a given style.
+     *
+     * @param viewElementName A view element name.
+     * @param properties The style (or styles list) to remove.
+     * @param selectable The selection or element to update.
+     */
+    private removeModelHtmlStyles;
+}