@ckeditor/ckeditor5-html-support 41.2.0 → 41.3.0-alpha.0

package/dist/types/generalhtmlsupport.d.ts

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

package/dist/types/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/dist/types/htmlcomment.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @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
+     */
+    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/dist/types/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;
+}

package/dist/types/index.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
+ */
+export { default as GeneralHtmlSupport } from './generalhtmlsupport.js';
+export { default as DataFilter } from './datafilter.js';
+export { default as DataSchema, type DataSchemaBlockElementDefinition } from './dataschema.js';
+export { default as HtmlComment } from './htmlcomment.js';
+export { default as FullPage } from './fullpage.js';
+export { default as HtmlPageDataProcessor } from './htmlpagedataprocessor.js';
+export type { GeneralHtmlSupportConfig } from './generalhtmlsupportconfig.js';
+export type { default as CodeBlockElementSupport } from './integrations/codeblock.js';
+export type { default as CustomElementSupport } from './integrations/customelement.js';
+export type { default as ListElementSupport } from './integrations/list.js';
+export type { default as DualContentModelElementSupport } from './integrations/dualcontent.js';
+export type { default as HeadingElementSupport } from './integrations/heading.js';
+export type { default as ImageElementSupport } from './integrations/image.js';
+export type { default as MediaEmbedElementSupport } from './integrations/mediaembed.js';
+export type { default as ScriptElementSupport } from './integrations/script.js';
+export type { default as StyleElementSupport } from './integrations/style.js';
+export type { default as TableElementSupport } from './integrations/table.js';
+import './augmentation.js';

package/dist/types/integrations/codeblock.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @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 DataFilter from '../datafilter.js';
+/**
+ * Provides the General HTML Support integration with {@link module:code-block/codeblock~CodeBlock Code Block} feature.
+ */
+export default class CodeBlockElementSupport extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof DataFilter];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "CodeBlockElementSupport";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/dist/types/integrations/customelement.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @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/integrations/customelement
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import DataSchema from '../dataschema.js';
+import DataFilter from '../datafilter.js';
+/**
+ * Provides the General HTML Support for custom elements (not registered in the {@link module:html-support/dataschema~DataSchema}).
+ */
+export default class CustomElementSupport extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof DataFilter, typeof DataSchema];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "CustomElementSupport";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/dist/types/integrations/dualcontent.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @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 DataFilter from '../datafilter.js';
+/**
+ * Provides the General HTML Support integration for elements which can behave like sectioning element (e.g. article) or
+ * element accepting only inline content (e.g. paragraph).
+ *
+ * The distinction between this two content models is important for choosing correct schema model and proper content conversion.
+ * As an example, it ensures that:
+ *
+ * * children elements paragraphing is enabled for sectioning elements only,
+ * * element and its content can be correctly handled by editing view (splitting and merging elements),
+ * * model element HTML is semantically correct and easier to work with.
+ *
+ * If element contains any block element, it will be treated as a sectioning element and registered using
+ * {@link module:html-support/dataschema~DataSchemaDefinition#model} and
+ * {@link module:html-support/dataschema~DataSchemaDefinition#modelSchema} in editor schema.
+ * Otherwise, it will be registered under {@link module:html-support/dataschema~DataSchemaBlockElementDefinition#paragraphLikeModel} model
+ * name with model schema accepting only inline content (inheriting from `$block`).
+ */
+export default class DualContentModelElementSupport extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof DataFilter];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "DualContentModelElementSupport";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Checks whether the given view element includes any other block element.
+     */
+    private _hasBlockContent;
+    /**
+     * Adds attribute filtering conversion for the given data schema.
+     */
+    private _addAttributeConversion;
+}

package/dist/types/integrations/heading.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @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/integrations/heading
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import { Enter } from 'ckeditor5/src/enter.js';
+import DataSchema from '../dataschema.js';
+/**
+ * Provides the General HTML Support integration with {@link module:heading/heading~Heading Heading} feature.
+ */
+export default class HeadingElementSupport extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof DataSchema, typeof Enter];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "HeadingElementSupport";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Registers all elements supported by HeadingEditing to enable custom attributes for those elements.
+     */
+    private registerHeadingElements;
+}

package/dist/types/integrations/image.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @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/integrations/image
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import DataFilter from '../datafilter.js';
+/**
+ * Provides the General HTML Support integration with the {@link module:image/image~Image Image} feature.
+ */
+export default class ImageElementSupport extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof DataFilter];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ImageElementSupport";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/dist/types/integrations/integrationutils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @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 type { DowncastWriter, ViewElement } from 'ckeditor5/src/engine.js';
+/**
+ * @module html-support/integrations/integrationutils
+ */
+/**
+ * Returns the first view element descendant matching the given view name.
+ * Includes view element itself.
+ *
+ * @internal
+ */
+export declare function getDescendantElement(writer: DowncastWriter, containerElement: ViewElement, elementName: string): ViewElement | undefined;

package/dist/types/integrations/list.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @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 DataFilter from '../datafilter.js';
+/**
+ * Provides the General HTML Support integration with the {@link module:list/list~List List} feature.
+ */
+export default class ListElementSupport extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof DataFilter];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ListElementSupport";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    afterInit(): void;
+}

package/dist/types/integrations/mediaembed.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @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/integrations/mediaembed
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import DataFilter from '../datafilter.js';
+/**
+ * Provides the General HTML Support integration with {@link module:media-embed/mediaembed~MediaEmbed Media Embed} feature.
+ */
+export default class MediaEmbedElementSupport extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof DataFilter];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "MediaEmbedElementSupport";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/dist/types/integrations/script.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @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/integrations/script
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import DataFilter from '../datafilter.js';
+/**
+ * Provides the General HTML Support for `script` elements.
+ */
+export default class ScriptElementSupport extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof DataFilter];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ScriptElementSupport";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/dist/types/integrations/style.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @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/integrations/style
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import DataFilter from '../datafilter.js';
+/**
+ * Provides the General HTML Support for `style` elements.
+ */
+export default class StyleElementSupport extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof DataFilter];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "StyleElementSupport";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/dist/types/integrations/table.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @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 DataFilter from '../datafilter.js';
+/**
+ * Provides the General HTML Support integration with {@link module:table/table~Table Table} feature.
+ */
+export default class TableElementSupport extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof DataFilter];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TableElementSupport";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/dist/types/schemadefinitions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @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 type { DataSchemaBlockElementDefinition, DataSchemaInlineElementDefinition } from './dataschema.js';
+/**
+ * @module html-support/schemadefinitions
+ */
+declare const _default: {
+    block: DataSchemaBlockElementDefinition[];
+    inline: DataSchemaInlineElementDefinition[];
+};
+export default _default;