@ckeditor/ckeditor5-html-embed 41.3.1 → 41.4.0

package/dist/translations/zh.umd.js

@@ -0,0 +1,11 @@
+/**
+ * @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
+ */
+
+( e => {
+const { [ 'zh' ]: { dictionary, getPluralForm } } = {"zh":{"dictionary":{"Insert HTML":"輸入HTML","HTML snippet":"HTML標籤","Paste raw HTML here...":"在此貼上純HTML","Edit source":"編輯HTML","Save changes":"儲存變更","No preview available":"無法顯示預覽","Empty snippet content":"HTML標籤中無內容"},getPluralForm(n){return 0;}}};
+e[ 'zh' ] ||= { dictionary: {}, getPluralForm: null };
+e[ 'zh' ].dictionary = Object.assign( e[ 'zh' ].dictionary, dictionary );
+e[ 'zh' ].getPluralForm = getPluralForm;
+} )( window.CKEDITOR_TRANSLATIONS ||= {} );

package/dist/types/augmentation.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import type { HtmlEmbed, HtmlEmbedCommand, HtmlEmbedConfig, HtmlEmbedEditing, HtmlEmbedUI } from './index.js';
+declare module '@ckeditor/ckeditor5-core' {
+    interface EditorConfig {
+        /**
+         * The configuration of the HTML embed feature. Introduced by the {@link module:html-embed/htmlembedediting~HtmlEmbedEditing}
+         * feature.
+         *
+         * Read more in {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+         */
+        htmlEmbed?: HtmlEmbedConfig;
+    }
+    interface PluginsMap {
+        [HtmlEmbed.pluginName]: HtmlEmbed;
+        [HtmlEmbedEditing.pluginName]: HtmlEmbedEditing;
+        [HtmlEmbedUI.pluginName]: HtmlEmbedUI;
+    }
+    interface CommandsMap {
+        htmlEmbed: HtmlEmbedCommand;
+    }
+}

package/dist/types/htmlembed.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module html-embed/htmlembed
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import { Widget } from 'ckeditor5/src/widget.js';
+import HtmlEmbedEditing from './htmlembedediting.js';
+import HtmlEmbedUI from './htmlembedui.js';
+/**
+ * The HTML embed feature.
+ *
+ * It allows inserting HTML snippets directly into the editor.
+ *
+ * For a detailed overview, check the {@glink features/html/html-embed HTML embed feature} documentation.
+ */
+export default class HtmlEmbed extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof HtmlEmbedEditing, typeof HtmlEmbedUI, typeof Widget];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "HtmlEmbed";
+}

package/dist/types/htmlembedcommand.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import { Command } from 'ckeditor5/src/core.js';
+/**
+ * The insert HTML embed element command.
+ *
+ * The command is registered by {@link module:html-embed/htmlembedediting~HtmlEmbedEditing} as `'htmlEmbed'`.
+ *
+ * To insert an empty HTML embed element at the current selection, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'htmlEmbed' );
+ * ```
+ *
+ * You can specify the initial content of a new HTML embed in the argument:
+ *
+ * ```ts
+ * editor.execute( 'htmlEmbed', '<b>Initial content.</b>' );
+ * ```
+ *
+ * To update the content of the HTML embed, select it in the model and pass the content in the argument:
+ *
+ * ```ts
+ * editor.execute( 'htmlEmbed', '<b>New content of an existing embed.</b>' );
+ * ```
+ */
+export default class HtmlEmbedCommand extends Command {
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command, which either:
+     *
+     * * creates and inserts a new HTML embed element if none was selected,
+     * * updates the content of the HTML embed if one was selected.
+     *
+     * @fires execute
+     * @param value When passed, the value (content) will be set on a new embed or a selected one.
+     */
+    execute(value?: string): void;
+}

package/dist/types/htmlembedconfig.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
+ */
+/**
+ * @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-embed/htmlembedconfig
+ */
+/**
+ * The configuration of the HTML embed feature.
+ *
+ * ```ts
+ * ClassicEditor
+ *   .create( editorElement, {
+ *     htmlEmbed: ... // HTML embed feature options.
+ *   } )
+ * 	 .then( ... )
+ *   .catch( ... );
+ * ```
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ */
+export interface HtmlEmbedConfig {
+    /**
+     * Whether the feature should render previews of the embedded HTML.
+     *
+     * When set to `true`, the feature will produce a preview of the inserted HTML based on a sanitized
+     * version of the HTML provided by the user.
+     *
+     * The function responsible for sanitizing the HTML needs to be specified in
+     * {@link module:html-embed/htmlembedconfig~HtmlEmbedConfig#sanitizeHtml `config.htmlEmbed.sanitizeHtml()`}.
+     *
+     * Read more about the security aspect of this feature in the {@glink features/html/html-embed#security "Security"} section of
+     * the {@glink features/html/html-embed HTML embed} feature guide.
+     */
+    showPreviews?: boolean;
+    /**
+     * Callback used to sanitize the HTML provided by the user when generating previews of it in the editor.
+     *
+     * We strongly recommend overwriting the default function to avoid XSS vulnerabilities.
+     *
+     * Read more about the security aspect of this feature in the {@glink features/html/html-embed#security "Security"} section of
+     * the {@glink features/html/html-embed HTML embed} feature guide.
+     *
+     * The function receives the input HTML (as a string), and should return an object
+     * that matches the {@link module:html-embed/htmlembedconfig~HtmlEmbedSanitizeOutput} interface.
+     *
+     * ```ts
+     * ClassicEditor
+     *   .create( editorElement, {
+     *     htmlEmbed: {
+     *       showPreviews: true,
+     *       sanitizeHtml( inputHtml ) {
+     *         // Strip unsafe elements and attributes, e.g.:
+     *         // the `<script>` elements and `on*` attributes.
+     *         const outputHtml = sanitize( inputHtml );
+     *
+     *         return {
+     *           html: outputHtml,
+     *           // true or false depending on whether the sanitizer stripped anything.
+     *           hasChanged: ...
+     *         };
+     *       },
+     *     }
+     *   } )
+     *   .then( ... )
+     *   .catch( ... );
+     * ```
+     *
+     * **Note:** The function is used only when the feature
+     * {@link module:html-embed/htmlembedconfig~HtmlEmbedConfig#showPreviews is configured to render previews}.
+     */
+    sanitizeHtml?: (html: string) => HtmlEmbedSanitizeOutput;
+}
+/**
+ * An object returned by the {@link module:html-embed/htmlembedconfig~HtmlEmbedConfig#sanitizeHtml} function.
+ */
+export interface HtmlEmbedSanitizeOutput {
+    /**
+     * An output (safe) HTML that will be inserted into the {@glink framework/architecture/editing-engine editing view}.
+     */
+    html: string;
+    /**
+     * A flag that indicates whether the output HTML is different than the input value.
+     */
+    hasChanged: boolean;
+}

package/dist/types/htmlembedediting.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module html-embed/htmlembedediting
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+import '../theme/htmlembed.css';
+/**
+ * The HTML embed editing feature.
+ */
+export default class HtmlEmbedEditing extends Plugin {
+    /**
+     * Keeps references to {@link module:ui/button/buttonview~ButtonView edit, save, and cancel} button instances created for
+     * each widget so they can be destroyed if they are no longer in DOM after the editing view was re-rendered.
+     */
+    private _widgetButtonViewReferences;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "HtmlEmbedEditing";
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Prepares converters for the feature.
+     */
+    private _setupConversion;
+}
+export interface RawHtmlApi {
+    makeEditable(): void;
+    save(newValue: string): void;
+    cancel(): void;
+}

package/dist/types/htmlembedui.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module html-embed/htmlembedui
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+/**
+ * The HTML embed UI plugin.
+ */
+export default class HtmlEmbedUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "HtmlEmbedUI";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Creates a button for html embed command to use either in toolbar or in menu bar.
+     */
+    private _createButton;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module html-embed
+ */
+export { default as HtmlEmbed } from './htmlembed.js';
+export { default as HtmlEmbedEditing } from './htmlembedediting.js';
+export { default as HtmlEmbedUI } from './htmlembedui.js';
+export type { default as HtmlEmbedCommand } from './htmlembedcommand.js';
+export type { HtmlEmbedConfig } from './htmlembedconfig.js';
+import './augmentation.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-html-embed",
-  "version": "41.3.1",
+  "version": "41.4.0",
   "description": "HTML embed feature for CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -13,7 +13,7 @@
   "type": "module",
   "main": "src/index.js",
   "dependencies": {
-    "ckeditor5": "41.3.1"
+    "ckeditor5": "41.4.0"
   },
   "author": "CKSource (http://cksource.com/)",
   "license": "GPL-2.0-or-later",
@@ -25,6 +25,7 @@
     "directory": "packages/ckeditor5-html-embed"
   },
   "files": [
+    "dist",
     "lang",
     "src/**/*.js",
     "src/**/*.d.ts",