@ckeditor/ckeditor5-media-embed 0.0.0-internal-20241017.0

package/src/mediaembedui.js

@@ -0,0 +1,132 @@
+/**
+ * @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 media-embed/mediaembedui
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import { ButtonView, CssTransitionDisablerMixin, MenuBarMenuListItemButtonView, Dialog } from 'ckeditor5/src/ui.js';
+import MediaFormView from './ui/mediaformview.js';
+import MediaEmbedEditing from './mediaembedediting.js';
+import mediaIcon from '../theme/icons/media.svg';
+/**
+ * The media embed UI plugin.
+ */
+export default class MediaEmbedUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [MediaEmbedEditing, Dialog];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'MediaEmbedUI';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        editor.ui.componentFactory.add('mediaEmbed', () => {
+            const t = this.editor.locale.t;
+            const button = this._createDialogButton(ButtonView);
+            button.tooltip = true;
+            button.label = t('Insert media');
+            return button;
+        });
+        editor.ui.componentFactory.add('menuBar:mediaEmbed', () => {
+            const t = this.editor.locale.t;
+            const button = this._createDialogButton(MenuBarMenuListItemButtonView);
+            button.label = t('Media');
+            return button;
+        });
+    }
+    /**
+     * Creates a button for menu bar that will show media embed dialog.
+     */
+    _createDialogButton(ButtonClass) {
+        const editor = this.editor;
+        const buttonView = new ButtonClass(editor.locale);
+        const command = editor.commands.get('mediaEmbed');
+        const dialogPlugin = this.editor.plugins.get('Dialog');
+        buttonView.icon = mediaIcon;
+        buttonView.bind('isEnabled').to(command, 'isEnabled');
+        buttonView.on('execute', () => {
+            if (dialogPlugin.id === 'mediaEmbed') {
+                dialogPlugin.hide();
+            }
+            else {
+                this._showDialog();
+            }
+        });
+        return buttonView;
+    }
+    _showDialog() {
+        const editor = this.editor;
+        const dialog = editor.plugins.get('Dialog');
+        const command = editor.commands.get('mediaEmbed');
+        const t = editor.locale.t;
+        if (!this._formView) {
+            const registry = editor.plugins.get(MediaEmbedEditing).registry;
+            this._formView = new (CssTransitionDisablerMixin(MediaFormView))(getFormValidators(editor.t, registry), editor.locale);
+            this._formView.on('submit', () => this._handleSubmitForm());
+        }
+        dialog.show({
+            id: 'mediaEmbed',
+            title: t('Insert media'),
+            content: this._formView,
+            isModal: true,
+            onShow: () => {
+                this._formView.url = command.value || '';
+                this._formView.resetFormStatus();
+                this._formView.urlInputView.fieldView.select();
+            },
+            actionButtons: [
+                {
+                    label: t('Cancel'),
+                    withText: true,
+                    onExecute: () => dialog.hide()
+                },
+                {
+                    label: t('Accept'),
+                    class: 'ck-button-action',
+                    withText: true,
+                    onExecute: () => this._handleSubmitForm()
+                }
+            ]
+        });
+    }
+    _handleSubmitForm() {
+        const editor = this.editor;
+        const dialog = editor.plugins.get('Dialog');
+        if (this._formView.isValid()) {
+            editor.execute('mediaEmbed', this._formView.url);
+            dialog.hide();
+            editor.editing.view.focus();
+        }
+    }
+}
+function getFormValidators(t, registry) {
+    return [
+        form => {
+            if (!form.url.length) {
+                return t('The URL must not be empty.');
+            }
+        },
+        form => {
+            if (!registry.hasMedia(form.url)) {
+                return t('This media URL is not supported.');
+            }
+        }
+    ];
+}

package/src/mediaregistry.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @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 media-embed/mediaregistry
+ */
+import type { DowncastWriter, ViewElement } from 'ckeditor5/src/engine.js';
+import { type Locale } from 'ckeditor5/src/utils.js';
+import type { MediaEmbedConfig, MediaEmbedProvider } from './mediaembedconfig.js';
+import type { MediaOptions } from './utils.js';
+/**
+ * A bridge between the raw media content provider definitions and the editor view content.
+ *
+ * It helps translating media URLs to corresponding {@link module:engine/view/element~Element view elements}.
+ *
+ * Mostly used by the {@link module:media-embed/mediaembedediting~MediaEmbedEditing} plugin.
+ */
+export default class MediaRegistry {
+    /**
+     * The {@link module:utils/locale~Locale} instance.
+     */
+    locale: Locale;
+    /**
+     * The media provider definitions available for the registry. Usually corresponding with the
+     * {@link module:media-embed/mediaembedconfig~MediaEmbedConfig media configuration}.
+     */
+    providerDefinitions: Array<MediaEmbedProvider>;
+    /**
+     * Creates an instance of the {@link module:media-embed/mediaregistry~MediaRegistry} class.
+     *
+     * @param locale The localization services instance.
+     * @param config The configuration of the media embed feature.
+     */
+    constructor(locale: Locale, config: MediaEmbedConfig);
+    /**
+     * Checks whether the passed URL is representing a certain media type allowed in the editor.
+     *
+     * @param url The URL to be checked
+     */
+    hasMedia(url: string): boolean;
+    /**
+     * For the given media URL string and options, it returns the {@link module:engine/view/element~Element view element}
+     * representing that media.
+     *
+     * **Note:** If no URL is specified, an empty view element is returned.
+     *
+     * @param writer The view writer used to produce a view element.
+     * @param url The URL to be translated into a view element.
+     */
+    getMediaViewElement(writer: DowncastWriter, url: string, options: MediaOptions): ViewElement;
+    /**
+     * Returns a `Media` instance for the given URL.
+     *
+     * @param url The URL of the media.
+     * @returns The `Media` instance or `null` when there is none.
+     */
+    private _getMedia;
+    /**
+     * Tries to match `url` to `pattern`.
+     *
+     * @param url The URL of the media.
+     * @param pattern The pattern that should accept the media URL.
+     */
+    private _getUrlMatches;
+}

package/src/mediaregistry.js

@@ -0,0 +1,232 @@
+/**
+ * @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 { IconView, Template } from 'ckeditor5/src/ui.js';
+import { logWarning, toArray } from 'ckeditor5/src/utils.js';
+import mediaPlaceholderIcon from '../theme/icons/media-placeholder.svg';
+const mediaPlaceholderIconViewBox = '0 0 64 42';
+/**
+ * A bridge between the raw media content provider definitions and the editor view content.
+ *
+ * It helps translating media URLs to corresponding {@link module:engine/view/element~Element view elements}.
+ *
+ * Mostly used by the {@link module:media-embed/mediaembedediting~MediaEmbedEditing} plugin.
+ */
+export default class MediaRegistry {
+    /**
+     * Creates an instance of the {@link module:media-embed/mediaregistry~MediaRegistry} class.
+     *
+     * @param locale The localization services instance.
+     * @param config The configuration of the media embed feature.
+     */
+    constructor(locale, config) {
+        const providers = config.providers;
+        const extraProviders = config.extraProviders || [];
+        const removedProviders = new Set(config.removeProviders);
+        const providerDefinitions = providers
+            .concat(extraProviders)
+            .filter(provider => {
+            const name = provider.name;
+            if (!name) {
+                /**
+                 * One of the providers (or extra providers) specified in the media embed configuration
+                 * has no name and will not be used by the editor. In order to get this media
+                 * provider working, double check your editor configuration.
+                 *
+                 * @error media-embed-no-provider-name
+                 */
+                logWarning('media-embed-no-provider-name', { provider });
+                return false;
+            }
+            return !removedProviders.has(name);
+        });
+        this.locale = locale;
+        this.providerDefinitions = providerDefinitions;
+    }
+    /**
+     * Checks whether the passed URL is representing a certain media type allowed in the editor.
+     *
+     * @param url The URL to be checked
+     */
+    hasMedia(url) {
+        return !!this._getMedia(url);
+    }
+    /**
+     * For the given media URL string and options, it returns the {@link module:engine/view/element~Element view element}
+     * representing that media.
+     *
+     * **Note:** If no URL is specified, an empty view element is returned.
+     *
+     * @param writer The view writer used to produce a view element.
+     * @param url The URL to be translated into a view element.
+     */
+    getMediaViewElement(writer, url, options) {
+        return this._getMedia(url).getViewElement(writer, options);
+    }
+    /**
+     * Returns a `Media` instance for the given URL.
+     *
+     * @param url The URL of the media.
+     * @returns The `Media` instance or `null` when there is none.
+     */
+    _getMedia(url) {
+        if (!url) {
+            return new Media(this.locale);
+        }
+        url = url.trim();
+        for (const definition of this.providerDefinitions) {
+            const previewRenderer = definition.html;
+            const pattern = toArray(definition.url);
+            for (const subPattern of pattern) {
+                const match = this._getUrlMatches(url, subPattern);
+                if (match) {
+                    return new Media(this.locale, url, match, previewRenderer);
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Tries to match `url` to `pattern`.
+     *
+     * @param url The URL of the media.
+     * @param pattern The pattern that should accept the media URL.
+     */
+    _getUrlMatches(url, pattern) {
+        // 1. Try to match without stripping the protocol and "www" subdomain.
+        let match = url.match(pattern);
+        if (match) {
+            return match;
+        }
+        // 2. Try to match after stripping the protocol.
+        let rawUrl = url.replace(/^https?:\/\//, '');
+        match = rawUrl.match(pattern);
+        if (match) {
+            return match;
+        }
+        // 3. Try to match after stripping the "www" subdomain.
+        rawUrl = rawUrl.replace(/^www\./, '');
+        match = rawUrl.match(pattern);
+        if (match) {
+            return match;
+        }
+        return null;
+    }
+}
+/**
+ * Represents media defined by the provider configuration.
+ *
+ * It can be rendered to the {@link module:engine/view/element~Element view element} and used in the editing or data pipeline.
+ */
+class Media {
+    constructor(locale, url, match, previewRenderer) {
+        this.url = this._getValidUrl(url);
+        this._locale = locale;
+        this._match = match;
+        this._previewRenderer = previewRenderer;
+    }
+    /**
+     * Returns the view element representation of the media.
+     *
+     * @param writer The view writer used to produce a view element.
+     */
+    getViewElement(writer, options) {
+        const attributes = {};
+        let viewElement;
+        if (options.renderForEditingView || (options.renderMediaPreview && this.url && this._previewRenderer)) {
+            if (this.url) {
+                attributes['data-oembed-url'] = this.url;
+            }
+            if (options.renderForEditingView) {
+                attributes.class = 'ck-media__wrapper';
+            }
+            const mediaHtml = this._getPreviewHtml(options);
+            viewElement = writer.createRawElement('div', attributes, (domElement, domConverter) => {
+                domConverter.setContentOf(domElement, mediaHtml);
+            });
+        }
+        else {
+            if (this.url) {
+                attributes.url = this.url;
+            }
+            viewElement = writer.createEmptyElement(options.elementName, attributes);
+        }
+        writer.setCustomProperty('media-content', true, viewElement);
+        return viewElement;
+    }
+    /**
+     * Returns the HTML string of the media content preview.
+     */
+    _getPreviewHtml(options) {
+        if (this._previewRenderer) {
+            return this._previewRenderer(this._match);
+        }
+        else {
+            // The placeholder only makes sense for editing view and media which have URLs.
+            // Placeholder is never displayed in data and URL-less media have no content.
+            if (this.url && options.renderForEditingView) {
+                return this._getPlaceholderHtml();
+            }
+            return '';
+        }
+    }
+    /**
+     * Returns the placeholder HTML when the media has no content preview.
+     */
+    _getPlaceholderHtml() {
+        const icon = new IconView();
+        const t = this._locale.t;
+        icon.content = mediaPlaceholderIcon;
+        icon.viewBox = mediaPlaceholderIconViewBox;
+        const placeholder = new Template({
+            tag: 'div',
+            attributes: {
+                class: 'ck ck-reset_all ck-media__placeholder'
+            },
+            children: [
+                {
+                    tag: 'div',
+                    attributes: {
+                        class: 'ck-media__placeholder__icon'
+                    },
+                    children: [icon]
+                },
+                {
+                    tag: 'a',
+                    attributes: {
+                        class: 'ck-media__placeholder__url',
+                        target: '_blank',
+                        rel: 'noopener noreferrer',
+                        href: this.url,
+                        'data-cke-tooltip-text': t('Open media in new tab')
+                    },
+                    children: [
+                        {
+                            tag: 'span',
+                            attributes: {
+                                class: 'ck-media__placeholder__url__text'
+                            },
+                            children: [this.url]
+                        }
+                    ]
+                }
+            ]
+        }).render();
+        return placeholder.outerHTML;
+    }
+    /**
+     * Returns the full URL to the specified media.
+     *
+     * @param url The URL of the media.
+     */
+    _getValidUrl(url) {
+        if (!url) {
+            return null;
+        }
+        if (url.match(/^https?/)) {
+            return url;
+        }
+        return 'https://' + url;
+    }
+}

package/src/ui/mediaformview.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @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 media-embed/ui/mediaformview
+ */
+import { type InputTextView, LabeledFieldView, View } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler, type Locale } from 'ckeditor5/src/utils.js';
+import '@ckeditor/ckeditor5-ui/theme/components/responsive-form/responsiveform.css';
+import '../../theme/mediaform.css';
+/**
+ * The media form view controller class.
+ *
+ * See {@link module:media-embed/ui/mediaformview~MediaFormView}.
+ */
+export default class MediaFormView extends View {
+    /**
+     * Tracks information about the DOM focus in the form.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * The value of the URL input.
+     */
+    mediaURLInputValue: string;
+    /**
+     * The URL input view.
+     */
+    urlInputView: LabeledFieldView<InputTextView>;
+    /**
+     * An array of form validators used by {@link #isValid}.
+     */
+    private readonly _validators;
+    /**
+     * The default info text for the {@link #urlInputView}.
+     */
+    private _urlInputViewInfoDefault?;
+    /**
+     * The info text with an additional tip for the {@link #urlInputView},
+     * displayed when the input has some value.
+     */
+    private _urlInputViewInfoTip?;
+    /**
+     * @param validators Form validators used by {@link #isValid}.
+     * @param locale The localization services instance.
+     */
+    constructor(validators: Array<(v: MediaFormView) => string | undefined>, locale: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the {@link #urlInputView}.
+     */
+    focus(): void;
+    /**
+     * The native DOM `value` of the {@link #urlInputView} element.
+     *
+     * **Note**: Do not confuse it with the {@link module:ui/inputtext/inputtextview~InputTextView#value}
+     * which works one way only and may not represent the actual state of the component in the DOM.
+     */
+    get url(): string;
+    set url(url: string);
+    /**
+     * Validates the form and returns `false` when some fields are invalid.
+     */
+    isValid(): boolean;
+    /**
+     * Cleans up the supplementary error and information text of the {@link #urlInputView}
+     * bringing them back to the state when the form has been displayed for the first time.
+     *
+     * See {@link #isValid}.
+     */
+    resetFormStatus(): void;
+    /**
+     * Creates a labeled input view.
+     *
+     * @returns Labeled input view instance.
+     */
+    private _createUrlInput;
+}

package/src/ui/mediaformview.js

@@ -0,0 +1,132 @@
+/**
+ * @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 media-embed/ui/mediaformview
+ */
+import { LabeledFieldView, View, createLabeledInputText, submitHandler } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler } from 'ckeditor5/src/utils.js';
+// See: #8833.
+// eslint-disable-next-line ckeditor5-rules/ckeditor-imports
+import '@ckeditor/ckeditor5-ui/theme/components/responsive-form/responsiveform.css';
+import '../../theme/mediaform.css';
+/**
+ * The media form view controller class.
+ *
+ * See {@link module:media-embed/ui/mediaformview~MediaFormView}.
+ */
+export default class MediaFormView extends View {
+    /**
+     * @param validators Form validators used by {@link #isValid}.
+     * @param locale The localization services instance.
+     */
+    constructor(validators, locale) {
+        super(locale);
+        this.focusTracker = new FocusTracker();
+        this.keystrokes = new KeystrokeHandler();
+        this.set('mediaURLInputValue', '');
+        this.urlInputView = this._createUrlInput();
+        this._validators = validators;
+        this.setTemplate({
+            tag: 'form',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-media-form',
+                    'ck-responsive-form'
+                ],
+                tabindex: '-1'
+            },
+            children: [
+                this.urlInputView
+            ]
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        submitHandler({
+            view: this
+        });
+        // Register the view in the focus tracker.
+        this.focusTracker.add(this.urlInputView.element);
+        // Start listening for the keystrokes coming from #element.
+        this.keystrokes.listenTo(this.element);
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        this.focusTracker.destroy();
+        this.keystrokes.destroy();
+    }
+    /**
+     * Focuses the {@link #urlInputView}.
+     */
+    focus() {
+        this.urlInputView.focus();
+    }
+    /**
+     * The native DOM `value` of the {@link #urlInputView} element.
+     *
+     * **Note**: Do not confuse it with the {@link module:ui/inputtext/inputtextview~InputTextView#value}
+     * which works one way only and may not represent the actual state of the component in the DOM.
+     */
+    get url() {
+        return this.urlInputView.fieldView.element.value.trim();
+    }
+    set url(url) {
+        this.urlInputView.fieldView.value = url.trim();
+    }
+    /**
+     * Validates the form and returns `false` when some fields are invalid.
+     */
+    isValid() {
+        this.resetFormStatus();
+        for (const validator of this._validators) {
+            const errorText = validator(this);
+            // One error per field is enough.
+            if (errorText) {
+                // Apply updated error.
+                this.urlInputView.errorText = errorText;
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Cleans up the supplementary error and information text of the {@link #urlInputView}
+     * bringing them back to the state when the form has been displayed for the first time.
+     *
+     * See {@link #isValid}.
+     */
+    resetFormStatus() {
+        this.urlInputView.errorText = null;
+        this.urlInputView.infoText = this._urlInputViewInfoDefault;
+    }
+    /**
+     * Creates a labeled input view.
+     *
+     * @returns Labeled input view instance.
+     */
+    _createUrlInput() {
+        const t = this.locale.t;
+        const labeledInput = new LabeledFieldView(this.locale, createLabeledInputText);
+        const inputField = labeledInput.fieldView;
+        this._urlInputViewInfoDefault = t('Paste the media URL in the input.');
+        this._urlInputViewInfoTip = t('Tip: Paste the URL into the content to embed faster.');
+        labeledInput.label = t('Media URL');
+        labeledInput.infoText = this._urlInputViewInfoDefault;
+        inputField.inputMode = 'url';
+        inputField.on('input', () => {
+            // Display the tip text only when there is some value. Otherwise fall back to the default info text.
+            labeledInput.infoText = inputField.element.value ? this._urlInputViewInfoTip : this._urlInputViewInfoDefault;
+            this.mediaURLInputValue = inputField.element.value.trim();
+        });
+        return labeledInput;
+    }
+}