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

package/src/generalhtmlsupport.js

@@ -0,0 +1,246 @@
+/**
+ * @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 { toArray } 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 { getHtmlAttributeName, modifyGhsAttribute } from './utils.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() {
+        return 'GeneralHtmlSupport';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [
+            DataFilter,
+            CodeBlockElementSupport,
+            DualContentModelElementSupport,
+            HeadingElementSupport,
+            ImageElementSupport,
+            MediaEmbedElementSupport,
+            ScriptElementSupport,
+            TableElementSupport,
+            StyleElementSupport,
+            ListElementSupport,
+            CustomElementSupport
+        ];
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        const dataFilter = editor.plugins.get(DataFilter);
+        // Load the allowed empty inline elements' configuration.
+        // Note that this modifies DataSchema so must be loaded before registering filtering rules.
+        dataFilter.loadAllowedEmptyElementsConfig(editor.config.get('htmlSupport.allowEmpty') || []);
+        // Load the filtering configuration.
+        dataFilter.loadAllowedConfig(editor.config.get('htmlSupport.allow') || []);
+        dataFilter.loadDisallowedConfig(editor.config.get('htmlSupport.disallow') || []);
+    }
+    /**
+     * Returns a GHS model attribute name related to a given view element name.
+     *
+     * @internal
+     * @param viewElementName A view element name.
+     */
+    getGhsAttributeNameForElement(viewElementName) {
+        const dataSchema = this.editor.plugins.get('DataSchema');
+        const definitions = Array.from(dataSchema.getDefinitionsForView(viewElementName, false));
+        const inlineDefinition = definitions.find(definition => (definition.isInline && !definitions[0].isObject));
+        if (inlineDefinition) {
+            return inlineDefinition.model;
+        }
+        return getHtmlAttributeName(viewElementName);
+    }
+    /**
+     * 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, className, selectable) {
+        const model = this.editor.model;
+        const ghsAttributeName = this.getGhsAttributeNameForElement(viewElementName);
+        model.change(writer => {
+            for (const item of getItemsToUpdateGhsAttribute(model, selectable, ghsAttributeName)) {
+                modifyGhsAttribute(writer, item, ghsAttributeName, 'classes', classes => {
+                    for (const value of toArray(className)) {
+                        classes.add(value);
+                    }
+                });
+            }
+        });
+    }
+    /**
+     * 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, className, selectable) {
+        const model = this.editor.model;
+        const ghsAttributeName = this.getGhsAttributeNameForElement(viewElementName);
+        model.change(writer => {
+            for (const item of getItemsToUpdateGhsAttribute(model, selectable, ghsAttributeName)) {
+                modifyGhsAttribute(writer, item, ghsAttributeName, 'classes', classes => {
+                    for (const value of toArray(className)) {
+                        classes.delete(value);
+                    }
+                });
+            }
+        });
+    }
+    /**
+     * 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.
+     */
+    setModelHtmlAttributes(viewElementName, attributes, selectable) {
+        const model = this.editor.model;
+        const ghsAttributeName = this.getGhsAttributeNameForElement(viewElementName);
+        model.change(writer => {
+            for (const item of getItemsToUpdateGhsAttribute(model, selectable, ghsAttributeName)) {
+                modifyGhsAttribute(writer, item, ghsAttributeName, 'attributes', attributesMap => {
+                    for (const [key, value] of Object.entries(attributes)) {
+                        attributesMap.set(key, value);
+                    }
+                });
+            }
+        });
+    }
+    /**
+     * 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.
+     */
+    removeModelHtmlAttributes(viewElementName, attributeName, selectable) {
+        const model = this.editor.model;
+        const ghsAttributeName = this.getGhsAttributeNameForElement(viewElementName);
+        model.change(writer => {
+            for (const item of getItemsToUpdateGhsAttribute(model, selectable, ghsAttributeName)) {
+                modifyGhsAttribute(writer, item, ghsAttributeName, 'attributes', attributesMap => {
+                    for (const key of toArray(attributeName)) {
+                        attributesMap.delete(key);
+                    }
+                });
+            }
+        });
+    }
+    /**
+     * 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.
+     */
+    setModelHtmlStyles(viewElementName, styles, selectable) {
+        const model = this.editor.model;
+        const ghsAttributeName = this.getGhsAttributeNameForElement(viewElementName);
+        model.change(writer => {
+            for (const item of getItemsToUpdateGhsAttribute(model, selectable, ghsAttributeName)) {
+                modifyGhsAttribute(writer, item, ghsAttributeName, 'styles', stylesMap => {
+                    for (const [key, value] of Object.entries(styles)) {
+                        stylesMap.set(key, value);
+                    }
+                });
+            }
+        });
+    }
+    /**
+     * 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.
+     */
+    removeModelHtmlStyles(viewElementName, properties, selectable) {
+        const model = this.editor.model;
+        const ghsAttributeName = this.getGhsAttributeNameForElement(viewElementName);
+        model.change(writer => {
+            for (const item of getItemsToUpdateGhsAttribute(model, selectable, ghsAttributeName)) {
+                modifyGhsAttribute(writer, item, ghsAttributeName, 'styles', stylesMap => {
+                    for (const key of toArray(properties)) {
+                        stylesMap.delete(key);
+                    }
+                });
+            }
+        });
+    }
+}
+/**
+ * Returns an iterator over an items in the selectable that accept given GHS attribute.
+ */
+function* getItemsToUpdateGhsAttribute(model, selectable, ghsAttributeName) {
+    if (!selectable) {
+        return;
+    }
+    if (!(Symbol.iterator in selectable) && selectable.is('documentSelection') && selectable.isCollapsed) {
+        if (model.schema.checkAttributeInSelection(selectable, ghsAttributeName)) {
+            yield selectable;
+        }
+    }
+    else {
+        for (const range of getValidRangesForSelectable(model, selectable, ghsAttributeName)) {
+            yield* range.getItems({ shallow: true });
+        }
+    }
+}
+/**
+ * Translates a given selectable to an iterable of ranges.
+ */
+function getValidRangesForSelectable(model, selectable, ghsAttributeName) {
+    if (!(Symbol.iterator in selectable) &&
+        (selectable.is('node') ||
+            selectable.is('$text') ||
+            selectable.is('$textProxy'))) {
+        if (model.schema.checkAttribute(selectable, ghsAttributeName)) {
+            return [model.createRangeOn(selectable)];
+        }
+        else {
+            return [];
+        }
+    }
+    else {
+        return model.schema.getValidRanges(model.createSelection(selectable).getRanges(), ghsAttributeName);
+    }
+}

package/src/generalhtmlsupportconfig.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @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/generalhtmlsupportconfig
+ */
+import type { MatcherObjectPattern } from 'ckeditor5/src/engine.js';
+/**
+ * The configuration of the General HTML Support feature.
+ * The option is used by the {@link module:html-support/generalhtmlsupport~GeneralHtmlSupport} feature.
+ *
+ * ```ts
+ * ClassicEditor
+ * 	.create( {
+ * 		htmlSupport: ... // General HTML Support feature config.
+ * 	} )
+ * 	.then( ... )
+ * 	.catch( ... );
+ * ```
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ */
+export interface GeneralHtmlSupportConfig {
+    /**
+     * The configuration of allowed content rules used by General HTML Support.
+     *
+     * Setting this configuration option will enable HTML features that are not explicitly supported by any other
+     * dedicated CKEditor 5 features.
+     *
+     * ```ts
+     * const htmlSupportConfig.allow = [
+     * 	{
+     * 		name: 'div',                      // Enable 'div' element support,
+     * 		classes: [ 'special-container' ], // allow 'special-container' class,
+     * 		styles: 'background',             // allow 'background' style,
+     * 		attributes: true                  // allow any attribute (can be empty).
+     * 	},
+     * 	{
+     * 		name: 'p',                                   // Extend existing Paragraph feature,
+     * 		classes: 'highlighted'                       // with 'highlighted' class,
+     * 		attributes: [
+     * 			{ key: 'data-i18n-context, value: true } // and i18n attribute.
+     * 		]
+     * 	}
+     * ];
+     * ```
+     */
+    allow?: Array<MatcherObjectPattern>;
+    /**
+     * The configuration of disallowed content rules used by General HTML Support.
+     *
+     * Setting this configuration option will disable listed HTML features.
+     *
+     * ```ts
+     * const htmlSupportConfig.disallow = [
+     * 	{
+     * 		name: /[\s\S]+/    // For every HTML feature,
+     * 		attributes: {
+     * 			key: /^on.*$/ // disable 'on*' attributes, like 'onClick', 'onError' etc.
+     * 		}
+     * 	}
+     * ];
+     * ```
+     */
+    disallow?: Array<MatcherObjectPattern>;
+    /**
+     * The configuration of allowed empty inline elements that should not be removed.
+     *
+     * Note that you should also add an appropriate entry to {@link #allow} list.
+     *
+     * ```ts
+     * const htmlSupportConfig.allowEmpty = [ 'i', 'span' ];
+     * ```
+     */
+    allowEmpty?: Array<string>;
+}

package/src/generalhtmlsupportconfig.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/htmlcomment.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @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/htmlcomment
+ */
+import type { Position, Range } from 'ckeditor5/src/engine.js';
+import { Plugin } from 'ckeditor5/src/core.js';
+/**
+ * The HTML comment feature. It preserves the HTML comments (`<!-- -->`) in the editor data.
+ *
+ * For a detailed overview, check the {@glink features/html/html-comments HTML comment feature documentation}.
+ */
+export default class HtmlComment extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "HtmlComment";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Creates an HTML comment on the specified position and returns its ID.
+     *
+     * *Note*: If two comments are created at the same position, the second comment will be inserted before the first one.
+     *
+     * @returns Comment ID. This ID can be later used to e.g. remove the comment from the content.
+     */
+    createHtmlComment(position: Position, content: string): string;
+    /**
+     * Removes an HTML comment with the given comment ID.
+     *
+     * It does nothing and returns `false` if the comment with the given ID does not exist.
+     * Otherwise it removes the comment and returns `true`.
+     *
+     * Note that a comment can be removed also by removing the content around the comment.
+     *
+     * @param commentID The ID of the comment to be removed.
+     * @returns `true` when the comment with the given ID was removed, `false` otherwise.
+     */
+    removeHtmlComment(commentID: string): boolean;
+    /**
+     * Gets the HTML comment data for the comment with a given ID.
+     *
+     * Returns `null` if the comment does not exist.
+     */
+    getHtmlCommentData(commentID: string): HtmlCommentData | null;
+    /**
+     * Gets all HTML comments in the given range.
+     *
+     * By default, it includes comments at the range boundaries.
+     *
+     * @param range
+     * @param options.skipBoundaries When set to `true` the range boundaries will be skipped.
+     * @returns HTML comment IDs
+     */
+    getHtmlCommentsInRange(range: Range, { skipBoundaries }?: {
+        skipBoundaries?: boolean | undefined;
+    }): Array<string>;
+}
+/**
+ * An interface for the HTML comments data.
+ *
+ * It consists of the {@link module:engine/model/position~Position `position`} and `content`.
+ */
+export interface HtmlCommentData {
+    position: Position;
+    content: string;
+}

package/src/htmlcomment.js

@@ -0,0 +1,224 @@
+/**
+ * @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 { Plugin } from 'ckeditor5/src/core.js';
+import { uid } from 'ckeditor5/src/utils.js';
+/**
+ * The HTML comment feature. It preserves the HTML comments (`<!-- -->`) in the editor data.
+ *
+ * For a detailed overview, check the {@glink features/html/html-comments HTML comment feature documentation}.
+ */
+export default class HtmlComment extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'HtmlComment';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        const loadedCommentsContent = new Map();
+        editor.data.processor.skipComments = false;
+        // Allow storing comment's content as the $root attribute with the name `$comment:<unique id>`.
+        editor.model.schema.addAttributeCheck((context, attributeName) => {
+            if (context.endsWith('$root') && attributeName.startsWith('$comment')) {
+                return true;
+            }
+        });
+        // Convert the `$comment` view element to `$comment:<unique id>` marker and store its content (the comment itself) as a $root
+        // attribute. The comment content is needed in the `dataDowncast` pipeline to re-create the comment node.
+        editor.conversion.for('upcast').elementToMarker({
+            view: '$comment',
+            model: viewElement => {
+                const markerUid = uid();
+                const markerName = `$comment:${markerUid}`;
+                const commentContent = viewElement.getCustomProperty('$rawContent');
+                loadedCommentsContent.set(markerName, commentContent);
+                return markerName;
+            }
+        });
+        // Convert the `$comment` marker to `$comment` UI element with `$rawContent` custom property containing the comment content.
+        editor.conversion.for('dataDowncast').markerToElement({
+            model: '$comment',
+            view: (modelElement, { writer }) => {
+                let root = undefined;
+                for (const rootName of this.editor.model.document.getRootNames()) {
+                    root = this.editor.model.document.getRoot(rootName);
+                    if (root.hasAttribute(modelElement.markerName)) {
+                        break;
+                    }
+                }
+                const markerName = modelElement.markerName;
+                const commentContent = root.getAttribute(markerName);
+                const comment = writer.createUIElement('$comment');
+                writer.setCustomProperty('$rawContent', commentContent, comment);
+                return comment;
+            }
+        });
+        // Remove comments' markers and their corresponding $root attributes, which are moved to the graveyard.
+        editor.model.document.registerPostFixer(writer => {
+            let changed = false;
+            const markers = editor.model.document.differ.getChangedMarkers().filter(marker => marker.name.startsWith('$comment:'));
+            for (const marker of markers) {
+                const { oldRange, newRange } = marker.data;
+                if (oldRange && newRange && oldRange.root == newRange.root) {
+                    // The marker was moved in the same root. Don't do anything.
+                    continue;
+                }
+                if (oldRange) {
+                    // The comment marker was moved from one root to another (most probably to the graveyard).
+                    // Remove the related attribute from the previous root.
+                    const oldRoot = oldRange.root;
+                    if (oldRoot.hasAttribute(marker.name)) {
+                        writer.removeAttribute(marker.name, oldRoot);
+                        changed = true;
+                    }
+                }
+                if (newRange) {
+                    const newRoot = newRange.root;
+                    if (newRoot.rootName == '$graveyard') {
+                        // Comment marker was moved to the graveyard -- remove it entirely.
+                        writer.removeMarker(marker.name);
+                        changed = true;
+                    }
+                    else if (!newRoot.hasAttribute(marker.name)) {
+                        // Comment marker was just added or was moved to another root - updated roots attributes.
+                        //
+                        // Added fallback to `''` for the comment content in case if someone incorrectly added just the marker "by hand"
+                        // and forgot to add the root attribute or add them in different change blocks.
+                        //
+                        // It caused an infinite loop in one of the unit tests.
+                        writer.setAttribute(marker.name, loadedCommentsContent.get(marker.name) || '', newRoot);
+                        changed = true;
+                    }
+                }
+            }
+            return changed;
+        });
+        // Delete all comment markers from the document before setting new data.
+        editor.data.on('set', () => {
+            for (const commentMarker of editor.model.markers.getMarkersGroup('$comment')) {
+                this.removeHtmlComment(commentMarker.name);
+            }
+        }, { priority: 'high' });
+        // Delete all comment markers that are within a removed range.
+        // Delete all comment markers at the limit element boundaries if the whole content of the limit element is removed.
+        editor.model.on('deleteContent', (evt, [selection]) => {
+            for (const range of selection.getRanges()) {
+                const limitElement = editor.model.schema.getLimitElement(range);
+                const firstPosition = editor.model.createPositionAt(limitElement, 0);
+                const lastPosition = editor.model.createPositionAt(limitElement, 'end');
+                let affectedCommentIDs;
+                if (firstPosition.isTouching(range.start) && lastPosition.isTouching(range.end)) {
+                    affectedCommentIDs = this.getHtmlCommentsInRange(editor.model.createRange(firstPosition, lastPosition));
+                }
+                else {
+                    affectedCommentIDs = this.getHtmlCommentsInRange(range, { skipBoundaries: true });
+                }
+                for (const commentMarkerID of affectedCommentIDs) {
+                    this.removeHtmlComment(commentMarkerID);
+                }
+            }
+        }, { priority: 'high' });
+    }
+    /**
+     * Creates an HTML comment on the specified position and returns its ID.
+     *
+     * *Note*: If two comments are created at the same position, the second comment will be inserted before the first one.
+     *
+     * @returns Comment ID. This ID can be later used to e.g. remove the comment from the content.
+     */
+    createHtmlComment(position, content) {
+        const id = uid();
+        const editor = this.editor;
+        const model = editor.model;
+        const root = model.document.getRoot(position.root.rootName);
+        const markerName = `$comment:${id}`;
+        return model.change(writer => {
+            const range = writer.createRange(position);
+            writer.addMarker(markerName, {
+                usingOperation: true,
+                affectsData: true,
+                range
+            });
+            writer.setAttribute(markerName, content, root);
+            return markerName;
+        });
+    }
+    /**
+     * Removes an HTML comment with the given comment ID.
+     *
+     * It does nothing and returns `false` if the comment with the given ID does not exist.
+     * Otherwise it removes the comment and returns `true`.
+     *
+     * Note that a comment can be removed also by removing the content around the comment.
+     *
+     * @param commentID The ID of the comment to be removed.
+     * @returns `true` when the comment with the given ID was removed, `false` otherwise.
+     */
+    removeHtmlComment(commentID) {
+        const editor = this.editor;
+        const marker = editor.model.markers.get(commentID);
+        if (!marker) {
+            return false;
+        }
+        editor.model.change(writer => {
+            writer.removeMarker(marker);
+        });
+        return true;
+    }
+    /**
+     * Gets the HTML comment data for the comment with a given ID.
+     *
+     * Returns `null` if the comment does not exist.
+     */
+    getHtmlCommentData(commentID) {
+        const editor = this.editor;
+        const marker = editor.model.markers.get(commentID);
+        if (!marker) {
+            return null;
+        }
+        let content = '';
+        for (const root of this.editor.model.document.getRoots()) {
+            if (root.hasAttribute(commentID)) {
+                content = root.getAttribute(commentID);
+                break;
+            }
+        }
+        return {
+            content,
+            position: marker.getStart()
+        };
+    }
+    /**
+     * Gets all HTML comments in the given range.
+     *
+     * By default, it includes comments at the range boundaries.
+     *
+     * @param range
+     * @param options.skipBoundaries When set to `true` the range boundaries will be skipped.
+     * @returns HTML comment IDs
+     */
+    getHtmlCommentsInRange(range, { skipBoundaries = false } = {}) {
+        const includeBoundaries = !skipBoundaries;
+        // Unfortunately, MarkerCollection#getMarkersAtPosition() filters out collapsed markers.
+        return Array.from(this.editor.model.markers.getMarkersGroup('$comment'))
+            .filter(marker => isCommentMarkerInRange(marker, range))
+            .map(marker => marker.name);
+        function isCommentMarkerInRange(commentMarker, range) {
+            const position = commentMarker.getRange().start;
+            return ((position.isAfter(range.start) || (includeBoundaries && position.isEqual(range.start))) &&
+                (position.isBefore(range.end) || (includeBoundaries && position.isEqual(range.end))));
+        }
+    }
+}

package/src/htmlpagedataprocessor.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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/htmlpagedataprocessor
+ */
+import { HtmlDataProcessor, type ViewDocumentFragment } from 'ckeditor5/src/engine.js';
+/**
+ * The full page HTML data processor class.
+ * This data processor implementation uses HTML as input and output data.
+ */
+export default class HtmlPageDataProcessor extends HtmlDataProcessor {
+    /**
+     * @inheritDoc
+     */
+    toView(data: string): ViewDocumentFragment;
+    /**
+     * @inheritDoc
+     */
+    toData(viewFragment: ViewDocumentFragment): string;
+}