@ckeditor/ckeditor5-media-embed 36.0.1 → 37.0.0-alpha.1

package/src/ui/mediaformview.js

@@ -2,350 +2,199 @@
  * @license Copyright (c) 2003-2023, 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 {
-	ButtonView,
-	FocusCycler,
-	LabeledFieldView,
-	View,
-	ViewCollection,
-	createLabeledInputText,
-	injectCssTransitionDisabler,
-	submitHandler
-} from 'ckeditor5/src/ui';
+import { ButtonView, FocusCycler, LabeledFieldView, View, ViewCollection, createLabeledInputText, submitHandler } from 'ckeditor5/src/ui';
 import { FocusTracker, KeystrokeHandler } from 'ckeditor5/src/utils';
 import { icons } from 'ckeditor5/src/core';
-
 // 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}.
- *
- * @extends module:ui/view~View
  */
 export default class MediaFormView extends View {
-	/**
-	 * @param {Array.<Function>} validators Form validators used by {@link #isValid}.
-	 * @param {module:utils/locale~Locale} [locale] The localization services instance.
-	 */
-	constructor( validators, locale ) {
-		super( locale );
-
-		const t = locale.t;
-
-		/**
-		 * Tracks information about the DOM focus in the form.
-		 *
-		 * @readonly
-		 * @member {module:utils/focustracker~FocusTracker}
-		 */
-		this.focusTracker = new FocusTracker();
-
-		/**
-		 * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
-		 *
-		 * @readonly
-		 * @member {module:utils/keystrokehandler~KeystrokeHandler}
-		 */
-		this.keystrokes = new KeystrokeHandler();
-
-		/**
-		 * The value of the URL input.
-		 *
-		 * @member {String} #mediaURLInputValue
-		 * @observable
-		 */
-		this.set( 'mediaURLInputValue', '' );
-
-		/**
-		 * The URL input view.
-		 *
-		 * @member {module:ui/labeledfield/labeledfieldview~LabeledFieldView}
-		 */
-		this.urlInputView = this._createUrlInput();
-
-		/**
-		 * The Save button view.
-		 *
-		 * @member {module:ui/button/buttonview~ButtonView}
-		 */
-		this.saveButtonView = this._createButton( t( 'Save' ), icons.check, 'ck-button-save' );
-		this.saveButtonView.type = 'submit';
-		this.saveButtonView.bind( 'isEnabled' ).to( this, 'mediaURLInputValue', value => !!value );
-
-		/**
-		 * The Cancel button view.
-		 *
-		 * @member {module:ui/button/buttonview~ButtonView}
-		 */
-		this.cancelButtonView = this._createButton( t( 'Cancel' ), icons.cancel, 'ck-button-cancel', 'cancel' );
-
-		/**
-		 * A collection of views that can be focused in the form.
-		 *
-		 * @readonly
-		 * @protected
-		 * @member {module:ui/viewcollection~ViewCollection}
-		 */
-		this._focusables = new ViewCollection();
-
-		/**
-		 * Helps cycling over {@link #_focusables} in the form.
-		 *
-		 * @readonly
-		 * @protected
-		 * @member {module:ui/focuscycler~FocusCycler}
-		 */
-		this._focusCycler = new FocusCycler( {
-			focusables: this._focusables,
-			focusTracker: this.focusTracker,
-			keystrokeHandler: this.keystrokes,
-			actions: {
-				// Navigate form fields backwards using the <kbd>Shift</kbd> + <kbd>Tab</kbd> keystroke.
-				focusPrevious: 'shift + tab',
-
-				// Navigate form fields forwards using the <kbd>Tab</kbd> key.
-				focusNext: 'tab'
-			}
-		} );
-
-		/**
-		 * An array of form validators used by {@link #isValid}.
-		 *
-		 * @readonly
-		 * @protected
-		 * @member {Array.<Function>}
-		 */
-		this._validators = validators;
-
-		this.setTemplate( {
-			tag: 'form',
-
-			attributes: {
-				class: [
-					'ck',
-					'ck-media-form',
-					'ck-responsive-form'
-				],
-
-				tabindex: '-1'
-			},
-
-			children: [
-				this.urlInputView,
-				this.saveButtonView,
-				this.cancelButtonView
-			]
-		} );
-
-		injectCssTransitionDisabler( this );
-
-		/**
-		 * The default info text for the {@link #urlInputView}.
-		 *
-		 * @private
-		 * @member {String} #_urlInputViewInfoDefault
-		 */
-
-		/**
-		 * The info text with an additional tip for the {@link #urlInputView},
-		 * displayed when the input has some value.
-		 *
-		 * @private
-		 * @member {String} #_urlInputViewInfoTip
-		 */
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	render() {
-		super.render();
-
-		submitHandler( {
-			view: this
-		} );
-
-		const childViews = [
-			this.urlInputView,
-			this.saveButtonView,
-			this.cancelButtonView
-		];
-
-		childViews.forEach( v => {
-			// Register the view as focusable.
-			this._focusables.add( v );
-
-			// Register the view in the focus tracker.
-			this.focusTracker.add( v.element );
-		} );
-
-		// Start listening for the keystrokes coming from #element.
-		this.keystrokes.listenTo( this.element );
-
-		const stopPropagation = data => data.stopPropagation();
-
-		// Since the form is in the dropdown panel which is a child of the toolbar, the toolbar's
-		// keystroke handler would take over the key management in the URL input. We need to prevent
-		// this ASAP. Otherwise, the basic caret movement using the arrow keys will be impossible.
-		this.keystrokes.set( 'arrowright', stopPropagation );
-		this.keystrokes.set( 'arrowleft', stopPropagation );
-		this.keystrokes.set( 'arrowup', stopPropagation );
-		this.keystrokes.set( 'arrowdown', stopPropagation );
-
-		// Intercept the `selectstart` event, which is blocked by default because of the default behavior
-		// of the DropdownView#panelView.
-		// TODO: blocking `selectstart` in the #panelView should be configurable per–drop–down instance.
-		this.listenTo( this.urlInputView.element, 'selectstart', ( evt, domEvt ) => {
-			domEvt.stopPropagation();
-		}, { priority: 'high' } );
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	destroy() {
-		super.destroy();
-
-		this.focusTracker.destroy();
-		this.keystrokes.destroy();
-	}
-
-	/**
-	 * Focuses the fist {@link #_focusables} in the form.
-	 */
-	focus() {
-		this._focusCycler.focusFirst();
-	}
-
-	/**
-	 * 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.
-	 *
-	 * @type {String}
-	 */
-	get url() {
-		return this.urlInputView.fieldView.element.value.trim();
-	}
-
-	set url( url ) {
-		this.urlInputView.fieldView.element.value = url.trim();
-	}
-
-	/**
-	 * Validates the form and returns `false` when some fields are invalid.
-	 *
-	 * @returns {Boolean}
-	 */
-	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.
-	 *
-	 * @private
-	 * @returns {module:ui/labeledfield/labeledfieldview~LabeledFieldView} 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.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;
-	}
-
-	/**
-	 * Creates a button view.
-	 *
-	 * @private
-	 * @param {String} label The button label.
-	 * @param {String} icon The button icon.
-	 * @param {String} className The additional button CSS class name.
-	 * @param {String} [eventName] An event name that the `ButtonView#execute` event will be delegated to.
-	 * @returns {module:ui/button/buttonview~ButtonView} The button view instance.
-	 */
-	_createButton( label, icon, className, eventName ) {
-		const button = new ButtonView( this.locale );
-
-		button.set( {
-			label,
-			icon,
-			tooltip: true
-		} );
-
-		button.extendTemplate( {
-			attributes: {
-				class: className
-			}
-		} );
-
-		if ( eventName ) {
-			button.delegate( 'execute' ).to( this, eventName );
-		}
-
-		return button;
-	}
+    /**
+     * @param validators Form validators used by {@link #isValid}.
+     * @param locale The localization services instance.
+     */
+    constructor(validators, locale) {
+        super(locale);
+        const t = locale.t;
+        this.focusTracker = new FocusTracker();
+        this.keystrokes = new KeystrokeHandler();
+        this.set('mediaURLInputValue', '');
+        this.urlInputView = this._createUrlInput();
+        this.saveButtonView = this._createButton(t('Save'), icons.check, 'ck-button-save');
+        this.saveButtonView.type = 'submit';
+        this.saveButtonView.bind('isEnabled').to(this, 'mediaURLInputValue', value => !!value);
+        this.cancelButtonView = this._createButton(t('Cancel'), icons.cancel, 'ck-button-cancel', 'cancel');
+        this._focusables = new ViewCollection();
+        this._focusCycler = new FocusCycler({
+            focusables: this._focusables,
+            focusTracker: this.focusTracker,
+            keystrokeHandler: this.keystrokes,
+            actions: {
+                // Navigate form fields backwards using the <kbd>Shift</kbd> + <kbd>Tab</kbd> keystroke.
+                focusPrevious: 'shift + tab',
+                // Navigate form fields forwards using the <kbd>Tab</kbd> key.
+                focusNext: 'tab'
+            }
+        });
+        this._validators = validators;
+        this.setTemplate({
+            tag: 'form',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-media-form',
+                    'ck-responsive-form'
+                ],
+                tabindex: '-1'
+            },
+            children: [
+                this.urlInputView,
+                this.saveButtonView,
+                this.cancelButtonView
+            ]
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        submitHandler({
+            view: this
+        });
+        const childViews = [
+            this.urlInputView,
+            this.saveButtonView,
+            this.cancelButtonView
+        ];
+        childViews.forEach(v => {
+            // Register the view as focusable.
+            this._focusables.add(v);
+            // Register the view in the focus tracker.
+            this.focusTracker.add(v.element);
+        });
+        // Start listening for the keystrokes coming from #element.
+        this.keystrokes.listenTo(this.element);
+        const stopPropagation = (data) => data.stopPropagation();
+        // Since the form is in the dropdown panel which is a child of the toolbar, the toolbar's
+        // keystroke handler would take over the key management in the URL input. We need to prevent
+        // this ASAP. Otherwise, the basic caret movement using the arrow keys will be impossible.
+        this.keystrokes.set('arrowright', stopPropagation);
+        this.keystrokes.set('arrowleft', stopPropagation);
+        this.keystrokes.set('arrowup', stopPropagation);
+        this.keystrokes.set('arrowdown', stopPropagation);
+        // Intercept the `selectstart` event, which is blocked by default because of the default behavior
+        // of the DropdownView#panelView.
+        // TODO: blocking `selectstart` in the #panelView should be configurable per–drop–down instance.
+        this.listenTo(this.urlInputView.element, 'selectstart', (evt, domEvt) => {
+            domEvt.stopPropagation();
+        }, { priority: 'high' });
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        this.focusTracker.destroy();
+        this.keystrokes.destroy();
+    }
+    /**
+     * Focuses the fist {@link #_focusables} in the form.
+     */
+    focus() {
+        this._focusCycler.focusFirst();
+    }
+    /**
+     * 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.element.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.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;
+    }
+    /**
+     * Creates a button view.
+     *
+     * @param label The button label.
+     * @param icon The button icon.
+     * @param className The additional button CSS class name.
+     * @param eventName An event name that the `ButtonView#execute` event will be delegated to.
+     * @returns The button view instance.
+     */
+    _createButton(label, icon, className, eventName) {
+        const button = new ButtonView(this.locale);
+        button.set({
+            label,
+            icon,
+            tooltip: true
+        });
+        button.extendTemplate({
+            attributes: {
+                class: className
+            }
+        });
+        if (eventName) {
+            button.delegate('execute').to(this, eventName);
+        }
+        return button;
+    }
 }
-
-/**
- * Fired when the form view is submitted (when one of the children triggered the submit event),
- * e.g. click on {@link #saveButtonView}.
- *
- * @event submit
- */
-
-/**
- * Fired when the form view is canceled, e.g. by a click on {@link #cancelButtonView}.
- *
- * @event cancel
- */

package/src/utils.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @license Copyright (c) 2003-2023, 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/utils
+ */
+import type { ViewContainerElement, Element, Model, Selectable, Selection, DowncastWriter, ViewDocumentSelection, ViewElement, DocumentSelection } from 'ckeditor5/src/engine';
+import type MediaRegistry from './mediaregistry';
+/**
+ * Converts a given {@link module:engine/view/element~Element} to a media embed widget:
+ * * Adds a {@link module:engine/view/element~Element#_setCustomProperty custom property} allowing to recognize the media widget element.
+ * * Calls the {@link module:widget/utils~toWidget} function with the proper element's label creator.
+ *
+ * @param writer An instance of the view writer.
+ * @param label The element's label.
+ */
+export declare function toMediaWidget(viewElement: ViewElement, writer: DowncastWriter, label: string): ViewElement;
+/**
+ * Returns a media widget editing view element if one is selected.
+ */
+export declare function getSelectedMediaViewWidget(selection: ViewDocumentSelection): ViewElement | null;
+/**
+ * Checks if a given view element is a media widget.
+ */
+export declare function isMediaWidget(viewElement: ViewElement): boolean;
+/**
+ * Creates a view element representing the media. Either a "semantic" one for the data pipeline:
+ *
+ * ```html
+ * <figure class="media">
+ * 	<oembed url="foo"></oembed>
+ * </figure>
+ * ```
+ *
+ * or a "non-semantic" (for the editing view pipeline):
+ *
+ * ```html
+ * <figure class="media">
+ * 	<div data-oembed-url="foo">[ non-semantic media preview for "foo" ]</div>
+ * </figure>
+ * ```
+ */
+export declare function createMediaFigureElement(writer: DowncastWriter, registry: MediaRegistry, url: string, options: MediaOptions): ViewContainerElement;
+/**
+ * Returns a selected media element in the model, if any.
+ */
+export declare function getSelectedMediaModelWidget(selection: Selection | DocumentSelection): Element | null;
+/**
+ * Creates a media element and inserts it into the model.
+ *
+ * **Note**: This method will use {@link module:engine/model/model~Model#insertContent `model.insertContent()`} logic of inserting content
+ * if no `insertPosition` is passed.
+ *
+ * @param url An URL of an embeddable media.
+ * @param findOptimalPosition If true it will try to find optimal position to insert media without breaking content
+ * in which a selection is.
+ */
+export declare function insertMedia(model: Model, url: string, selectable: Selectable, findOptimalPosition: boolean): void;
+/**
+ * Type for commonly grouped function parameters across this package.
+ */
+export type MediaOptions = {
+    elementName: string;
+    renderMediaPreview?: boolean;
+    renderForEditingView?: boolean;
+};