@ckeditor/ckeditor5-upload 41.2.0 → 41.3.0-alpha.0

package/dist/types/filerepository.d.ts

@@ -0,0 +1,342 @@
+/**
+ * @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 upload/filerepository
+ */
+import { Plugin, PendingActions } from '@ckeditor/ckeditor5-core';
+import { Collection } from '@ckeditor/ckeditor5-utils';
+/**
+ * File repository plugin. A central point for managing file upload.
+ *
+ * To use it, first you need an upload adapter. Upload adapter's job is to handle communication with the server
+ * (sending the file and handling server's response). You can use one of the existing plugins introducing upload adapters
+ * (e.g. {@link module:easy-image/cloudservicesuploadadapter~CloudServicesUploadAdapter} or
+ * {@link module:adapter-ckfinder/uploadadapter~CKFinderUploadAdapter}) or write your own one – see
+ * the {@glink framework/deep-dive/upload-adapter Custom image upload adapter deep-dive} guide.
+ *
+ * Then, you can use {@link module:upload/filerepository~FileRepository#createLoader `createLoader()`} and the returned
+ * {@link module:upload/filerepository~FileLoader} instance to load and upload files.
+ */
+export default class FileRepository extends Plugin {
+    /**
+     * Collection of loaders associated with this repository.
+     */
+    loaders: Collection<FileLoader>;
+    /**
+     * A factory function which should be defined before using `FileRepository`.
+     *
+     * It should return a new instance of {@link module:upload/filerepository~UploadAdapter} that will be used to upload files.
+     * {@link module:upload/filerepository~FileLoader} instance associated with the adapter
+     * will be passed to that function.
+     *
+     * For more information and example see {@link module:upload/filerepository~UploadAdapter}.
+     */
+    createUploadAdapter?: (loader: FileLoader) => UploadAdapter;
+    /**
+     * Loaders mappings used to retrieve loaders references.
+     */
+    private _loadersMap;
+    /**
+     * Reference to a pending action registered in a {@link module:core/pendingactions~PendingActions} plugin
+     * while upload is in progress. When there is no upload then value is `null`.
+     */
+    private _pendingAction;
+    /**
+     * Number of bytes uploaded.
+     *
+     * @readonly
+     * @observable
+     */
+    uploaded: number;
+    /**
+     * Number of total bytes to upload.
+     *
+     * It might be different than the file size because of headers and additional data.
+     * It contains `null` if value is not available yet, so it's better to use {@link #uploadedPercent} to monitor
+     * the progress.
+     *
+     * @readonly
+     * @observable
+     */
+    uploadTotal: number | null;
+    /**
+     * Upload progress in percents.
+     *
+     * @readonly
+     * @observable
+     */
+    uploadedPercent: number;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "FileRepository";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof PendingActions];
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Returns the loader associated with specified file or promise.
+     *
+     * To get loader by id use `fileRepository.loaders.get( id )`.
+     *
+     * @param fileOrPromise Native file or promise handle.
+     */
+    getLoader(fileOrPromise: File | Promise<File>): FileLoader | null;
+    /**
+     * Creates a loader instance for the given file.
+     *
+     * Requires {@link #createUploadAdapter} factory to be defined.
+     *
+     * @param fileOrPromise Native File object or native Promise object which resolves to a File.
+     */
+    createLoader(fileOrPromise: File | Promise<File>): FileLoader | null;
+    /**
+     * Destroys the given loader.
+     *
+     * @param fileOrPromiseOrLoader File or Promise associated with that loader or loader itself.
+     */
+    destroyLoader(fileOrPromiseOrLoader: File | Promise<File> | FileLoader): void;
+    /**
+     * Registers or deregisters pending action bound with upload progress.
+     */
+    private _updatePendingAction;
+}
+declare const FileLoader_base: {
+    new (): import("@ckeditor/ckeditor5-utils").Observable;
+    prototype: import("@ckeditor/ckeditor5-utils").Observable;
+};
+/**
+ * File loader class.
+ *
+ * It is used to control the process of reading the file and uploading it using the specified upload adapter.
+ */
+declare class FileLoader extends FileLoader_base {
+    /**
+     * Unique id of FileLoader instance.
+     *
+     * @readonly
+     */
+    readonly id: string;
+    /**
+     * Additional wrapper over the initial file promise passed to this loader.
+     */
+    private _filePromiseWrapper;
+    /**
+     * Adapter instance associated with this file loader.
+     */
+    private _adapter;
+    /**
+     * FileReader used by FileLoader.
+     */
+    private _reader;
+    /**
+     * Current status of FileLoader. It can be one of the following:
+     *
+     * * 'idle',
+     * * 'reading',
+     * * 'uploading',
+     * * 'aborted',
+     * * 'error'.
+     *
+     * When reading status can change in a following way:
+     *
+     * `idle` -> `reading` -> `idle`
+     * `idle` -> `reading -> `aborted`
+     * `idle` -> `reading -> `error`
+     *
+     * When uploading status can change in a following way:
+     *
+     * `idle` -> `uploading` -> `idle`
+     * `idle` -> `uploading` -> `aborted`
+     * `idle` -> `uploading` -> `error`
+     *
+     * @readonly
+     * @observable
+     */
+    status: 'idle' | 'reading' | 'uploading' | 'aborted' | 'error';
+    /**
+     * Number of bytes uploaded.
+     *
+     * @readonly
+     * @observable
+     */
+    uploaded: number;
+    /**
+     * Number of total bytes to upload.
+     *
+     * @readonly
+     * @observable
+     */
+    uploadTotal: number | null;
+    /**
+     * Upload progress in percents.
+     *
+     * @readonly
+     * @observable
+     */
+    uploadedPercent: number;
+    /**
+     * Response of the upload.
+     *
+     * @readonly
+     * @observable
+     */
+    uploadResponse?: UploadResponse | null;
+    /**
+     * Creates a new instance of `FileLoader`.
+     *
+     * @param filePromise A promise which resolves to a file instance.
+     * @param uploadAdapterCreator The function which returns {@link module:upload/filerepository~UploadAdapter} instance.
+     */
+    constructor(filePromise: Promise<File>, uploadAdapterCreator: (loader: FileLoader) => UploadAdapter);
+    /**
+     * A `Promise` which resolves to a `File` instance associated with this file loader.
+     */
+    get file(): Promise<File | null>;
+    /**
+     * Returns the file data. To read its data, you need for first load the file
+     * by using the {@link module:upload/filerepository~FileLoader#read `read()`} method.
+     */
+    get data(): string | undefined;
+    /**
+     * Reads file using {@link module:upload/filereader~FileReader}.
+     *
+     * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `filerepository-read-wrong-status` when status
+     * is different than `idle`.
+     *
+     * Example usage:
+     *
+     * ```ts
+     * fileLoader.read()
+     * 	.then( data => { ... } )
+     * 	.catch( err => {
+     * 		if ( err === 'aborted' ) {
+     * 			console.log( 'Reading aborted.' );
+     * 		} else {
+     * 			console.log( 'Reading error.', err );
+     * 		}
+     * 	} );
+     * ```
+     *
+     * @returns Returns promise that will be resolved with read data. Promise will be rejected if error
+     * occurs or if read process is aborted.
+     */
+    read(): Promise<string>;
+    /**
+     * Reads file using the provided {@link module:upload/filerepository~UploadAdapter}.
+     *
+     * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `filerepository-upload-wrong-status` when status
+     * is different than `idle`.
+     * Example usage:
+     *
+     * ```ts
+     * fileLoader.upload()
+     * 	.then( data => { ... } )
+     * 	.catch( e => {
+     * 		if ( e === 'aborted' ) {
+     * 			console.log( 'Uploading aborted.' );
+     * 		} else {
+     * 			console.log( 'Uploading error.', e );
+     * 		}
+     * 	} );
+     * ```
+     *
+     * @returns Returns promise that will be resolved with response data. Promise will be rejected if error
+     * occurs or if read process is aborted.
+     */
+    upload(): Promise<UploadResponse>;
+    /**
+     * Aborts loading process.
+     */
+    abort(): void;
+    /**
+     * Performs cleanup.
+     *
+     * @internal
+     */
+    _destroy(): void;
+    /**
+     * Wraps a given file promise into another promise giving additional
+     * control (resolving, rejecting, checking if fulfilled) over it.
+     *
+     * @param filePromise The initial file promise to be wrapped.
+     */
+    private _createFilePromiseWrapper;
+}
+export type { FileLoader };
+/**
+ * Upload adapter interface used by the {@link module:upload/filerepository~FileRepository file repository}
+ * to handle file upload. An upload adapter is a bridge between the editor and server that handles file uploads.
+ * It should contain a logic necessary to initiate an upload process and monitor its progress.
+ *
+ * Learn how to develop your own upload adapter for CKEditor 5 in the
+ * {@glink framework/deep-dive/upload-adapter "Custom upload adapter"} guide.
+ *
+ * @interface UploadAdapter
+ */
+export interface UploadAdapter {
+    /**
+     * Executes the upload process.
+     * This method should return a promise that will resolve when data will be uploaded to server. Promise should be
+     * resolved with an object containing information about uploaded file:
+     *
+     * ```json
+     * {
+     * 	default: 'http://server/default-size.image.png'
+     * }
+     * ```
+     *
+     * Additionally, other image sizes can be provided:
+     *
+     * ```json
+     * {
+     * 	default: 'http://server/default-size.image.png',
+     * 	'160': 'http://server/size-160.image.png',
+     * 	'500': 'http://server/size-500.image.png',
+     * 	'1000': 'http://server/size-1000.image.png',
+     * 	'1052': 'http://server/default-size.image.png'
+     * }
+     * ```
+     *
+     * You can also pass additional properties from the server. In this case you need to wrap URLs
+     * in the `urls` object and pass additional properties along the `urls` property.
+     *
+     * ```json
+     * {
+     * 	myCustomProperty: 'foo',
+     * 	urls: {
+     * 		default: 'http://server/default-size.image.png',
+     * 		'160': 'http://server/size-160.image.png',
+     * 		'500': 'http://server/size-500.image.png',
+     * 		'1000': 'http://server/size-1000.image.png',
+     * 		'1052': 'http://server/default-size.image.png'
+     * 	}
+     * }
+     * ```
+     *
+     * NOTE: When returning multiple images, the widest returned one should equal the default one. It is essential to
+     * correctly set `width` attribute of the image. See this discussion:
+     * https://github.com/ckeditor/ckeditor5-easy-image/issues/4 for more information.
+     *
+     * Take a look at {@link module:upload/filerepository~UploadAdapter example Adapter implementation} and
+     * {@link module:upload/filerepository~FileRepository#createUploadAdapter createUploadAdapter method}.
+     *
+     * @returns Promise that should be resolved when data is uploaded.
+     */
+    upload(): Promise<UploadResponse>;
+    /**
+     * Aborts the upload process.
+     * After aborting it should reject promise returned from {@link #upload upload()}.
+     *
+     * Take a look at {@link module:upload/filerepository~UploadAdapter example Adapter implementation} and
+     * {@link module:upload/filerepository~FileRepository#createUploadAdapter createUploadAdapter method}.
+     */
+    abort?(): void;
+}
+export type UploadResponse = Record<string, unknown>;

package/dist/types/index.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
+ */
+/**
+ * @module upload
+ */
+export { default as FileRepository, type UploadAdapter, type UploadResponse, type FileLoader } from './filerepository.js';
+export { default as FileDialogButtonView } from './ui/filedialogbuttonview.js';
+export { default as Base64UploadAdapter } from './adapters/base64uploadadapter.js';
+export { default as SimpleUploadAdapter } from './adapters/simpleuploadadapter.js';
+export type { SimpleUploadConfig } from './uploadconfig.js';
+import './augmentation.js';

package/dist/types/ui/filedialogbuttonview.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @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 upload/ui/filedialogbuttonview
+ */
+import { ButtonView } from '@ckeditor/ckeditor5-ui';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * The file dialog button view.
+ *
+ * This component provides a button that opens the native file selection dialog.
+ * It can be used to implement the UI of a file upload feature.
+ *
+ * ```ts
+ * const view = new FileDialogButtonView( locale );
+ *
+ * view.set( {
+ * 	acceptedType: 'image/*',
+ * 	allowMultipleFiles: true
+ * 	label: t( 'Insert image' ),
+ * 	icon: imageIcon,
+ * 	tooltip: true
+ * } );
+ *
+ * view.on( 'done', ( evt, files ) => {
+ * 	for ( const file of Array.from( files ) ) {
+ * 		console.log( 'Selected file', file );
+ * 	}
+ * } );
+ * ```
+ */
+export default class FileDialogButtonView extends ButtonView {
+    /**
+     * The button view of the component.
+     *
+     * @deprecated
+     */
+    buttonView: ButtonView;
+    /**
+     * A hidden `<input>` view used to execute file dialog.
+     */
+    private _fileInputView;
+    /**
+     * Accepted file types. Can be provided in form of file extensions, media type or one of:
+     * * `audio/*`,
+     * * `video/*`,
+     * * `image/*`.
+     *
+     * @observable
+     */
+    acceptedType: string;
+    /**
+     * Indicates if multiple files can be selected. Defaults to `true`.
+     *
+     * @observable
+     */
+    allowMultipleFiles: boolean;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+}
+/**
+ * Fired when file dialog is closed with file selected.
+ *
+ * ```ts
+ * view.on( 'done', ( evt, files ) => {
+ * 	for ( const file of files ) {
+ * 		console.log( 'Selected file', file );
+ * 	}
+ * }
+ * ```
+ */
+export type FileInputViewDoneEvent = {
+    name: 'done';
+    args: [files: FileList];
+};

package/dist/types/uploadconfig.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
+ */
+/**
+ * @module upload/uploadconfig
+ */
+/**
+ * The configuration of the {@link module:upload/adapters/simpleuploadadapter~SimpleUploadAdapter simple upload adapter}.
+ *
+ * ```ts
+ * ClassicEditor
+ * 	.create( editorElement, {
+ * 		simpleUpload: {
+ * 			// The URL the images are uploaded to.
+ * 			uploadUrl: 'http://example.com',
+ *
+ * 			// Headers sent along with the XMLHttpRequest to the upload server.
+ * 			headers: {
+ * 				...
+ * 			}
+ * 		}
+ * 	} );
+ * 	.then( ... )
+ * 	.catch( ... );
+ * ```
+ *
+ * See the {@glink features/images/image-upload/simple-upload-adapter "Simple upload adapter"} guide to learn more.
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor configuration options}.
+ */
+export interface SimpleUploadConfig {
+    /**
+     * The path (URL) to the server (application) which handles the file upload. When specified, enables the automatic
+     * upload of resources (images) inserted into the editor content.
+     *
+     * Learn more about the server application requirements in the
+     * {@glink features/images/image-upload/simple-upload-adapter#server-side-configuration "Server-side configuration"} section
+     * of the feature guide.
+     */
+    uploadUrl: string;
+    /**
+     * An object that defines additional [headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) sent with
+     * the request to the server during the upload. This is the right place to implement security mechanisms like
+     * authentication and [CSRF](https://developer.mozilla.org/en-US/docs/Glossary/CSRF) protection.
+     *
+     * ```ts
+     * ClassicEditor
+     * 	.create( editorElement, {
+     * 		simpleUpload: {
+     * 			headers: {
+     * 				'X-CSRF-TOKEN': 'CSRF-Token',
+     * 				Authorization: 'Bearer <JSON Web Token>'
+     * 			}
+     * 		}
+     * 	} );
+     * 	.then( ... )
+     * 	.catch( ... );
+     * ```
+     *
+     * Learn more about the server application requirements in the
+     * {@glink features/images/image-upload/simple-upload-adapter#server-side-configuration "Server-side configuration"} section
+     * of the feature guide.
+     */
+    headers?: Record<string, string>;
+    /**
+     * This flag enables the
+     * [`withCredentials`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials)
+     * property of the request sent to the server during the upload. It affects cross-site requests only and, for instance,
+     * allows credentials such as cookies to be sent along with the request.
+     *
+     * ```ts
+     * ClassicEditor
+     * 	.create( editorElement, {
+     * 		simpleUpload: {
+     * 			withCredentials: true
+     * 		}
+     * 	} );
+     * 	.then( ... )
+     * 	.catch( ... );
+     * ```
+     *
+     * Learn more about the server application requirements in the
+     * {@glink features/images/image-upload/simple-upload-adapter#server-side-configuration "Server-side configuration"} section
+     * of the feature guide.
+     *
+     * @default false
+     */
+    withCredentials?: boolean;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-upload",
-  "version": "41.2.0",
+  "version": "41.3.0-alpha.0",
   "description": "Upload feature for CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -12,9 +12,9 @@
   "type": "module",
   "main": "src/index.js",
   "dependencies": {
-    "@ckeditor/ckeditor5-core": "41.2.0",
-    "@ckeditor/ckeditor5-utils": "41.2.0",
-    "@ckeditor/ckeditor5-ui": "41.2.0"
+    "@ckeditor/ckeditor5-core": "41.3.0-alpha.0",
+    "@ckeditor/ckeditor5-utils": "41.3.0-alpha.0",
+    "@ckeditor/ckeditor5-ui": "41.3.0-alpha.0"
   },
   "author": "CKSource (http://cksource.com/)",
   "license": "GPL-2.0-or-later",
@@ -26,6 +26,7 @@
     "directory": "packages/ckeditor5-upload"
   },
   "files": [
+    "dist",
     "lang",
     "src/**/*.js",
     "src/**/*.d.ts",