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

package/dist/types/augmentation.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
+ */
+import type { CKBox, CKBoxCommand, CKBoxConfig, CKBoxEditing, CKBoxImageEdit, CKBoxImageEditEditing, CKBoxImageEditCommand, CKBoxImageEditUI } from './index.js';
+declare module '@ckeditor/ckeditor5-core' {
+    interface EditorConfig {
+        /**
+         * The configuration of the {@link module:ckbox/ckbox~CKBox CKBox feature}.
+         *
+         * Read more in {@link module:ckbox/ckboxconfig~CKBoxConfig}.
+         */
+        ckbox?: CKBoxConfig;
+    }
+    interface PluginsMap {
+        [CKBox.pluginName]: CKBox;
+        [CKBoxEditing.pluginName]: CKBoxEditing;
+        [CKBoxImageEdit.pluginName]: CKBoxImageEdit;
+        [CKBoxImageEditEditing.pluginName]: CKBoxImageEditEditing;
+        [CKBoxImageEditUI.pluginName]: CKBoxImageEditUI;
+    }
+    interface CommandsMap {
+        ckbox: CKBoxCommand;
+        ckboxImageEdit: CKBoxImageEditCommand;
+    }
+}
+declare global {
+    var CKBox: {
+        mount(wrapper: Element, options: Record<string, unknown>): void;
+        mountImageEditor(wrapper: Element, options: Record<string, unknown>): void;
+    };
+}

package/dist/types/ckbox.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @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 ckbox/ckbox
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import CKBoxUI from './ckboxui.js';
+import CKBoxEditing from './ckboxediting.js';
+/**
+ * The CKBox feature, a bridge between the CKEditor 5 WYSIWYG editor and the CKBox file manager and uploader.
+ *
+ * This is a "glue" plugin which enables:
+ *
+ * * {@link module:ckbox/ckboxediting~CKBoxEditing},
+ * * {@link module:ckbox/ckboxui~CKBoxUI},
+ *
+ * See the {@glink features/file-management/ckbox CKBox integration} guide to learn how to configure and use this feature.
+ *
+ * Check out the {@glink features/images/image-upload/image-upload Image upload} guide to learn about other ways to upload
+ * images into CKEditor 5.
+ */
+export default class CKBox extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "CKBox";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof CKBoxEditing, typeof CKBoxUI];
+}

package/dist/types/ckboxcommand.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @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, type Editor } from 'ckeditor5/src/core.js';
+import type { CKBoxAssetDefinition, CKBoxAssetImageAttributesDefinition, CKBoxRawAssetDefinition } from './ckboxconfig.js';
+/**
+ * The CKBox command. It is used by the {@link module:ckbox/ckboxediting~CKBoxEditing CKBox editing feature} to open the CKBox file manager.
+ * The file manager allows inserting an image or a link to a file into the editor content.
+ *
+ * ```ts
+ * editor.execute( 'ckbox' );
+ * ```
+ *
+ * **Note:** This command uses other features to perform the following tasks:
+ * - To insert images it uses the {@link module:image/image/insertimagecommand~InsertImageCommand 'insertImage'} command from the
+ * {@link module:image/image~Image Image feature}.
+ * - To insert links to other files it uses the {@link module:link/linkcommand~LinkCommand 'link'} command from the
+ * {@link module:link/link~Link Link feature}.
+ */
+export default class CKBoxCommand extends Command {
+    value: boolean;
+    /**
+     * A set of all chosen assets. They are stored temporarily and they are automatically removed 1 second after being chosen.
+     * Chosen assets have to be "remembered" for a while to be able to map the given asset with the element inserted into the model.
+     * This association map is then used to set the ID on the model element.
+     *
+     * All chosen assets are automatically removed after the timeout, because (theoretically) it may happen that they will never be
+     * inserted into the model, even if the {@link module:link/linkcommand~LinkCommand `'link'`} command or the
+     * {@link module:image/image/insertimagecommand~InsertImageCommand `'insertImage'`} command is enabled. Such a case may arise when
+     * another plugin blocks the command execution. Then, in order not to keep the chosen (but not inserted) assets forever, we delete
+     * them automatically to prevent memory leakage. The 1 second timeout is enough to insert the asset into the model and extract the
+     * ID from the chosen asset.
+     *
+     * The assets are stored only if
+     * the {@link module:ckbox/ckboxconfig~CKBoxConfig#ignoreDataId `config.ckbox.ignoreDataId`} option is set to `false` (by default).
+     *
+     * @internal
+     */
+    readonly _chosenAssets: Set<CKBoxAssetDefinition>;
+    /**
+     * The DOM element that acts as a mounting point for the CKBox dialog.
+     */
+    private _wrapper;
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * @inheritDoc
+     */
+    execute(): void;
+    /**
+     * Indicates if the CKBox dialog is already opened.
+     *
+     * @protected
+     * @returns {Boolean}
+     */
+    private _getValue;
+    /**
+     * Checks whether the command can be enabled in the current context.
+     */
+    private _checkEnabled;
+    /**
+     * Creates the options object for the CKBox dialog.
+     *
+     * @returns The object with properties:
+     * - theme The theme for CKBox dialog.
+     * - language The language for CKBox dialog.
+     * - tokenUrl The token endpoint URL.
+     * - serviceOrigin The base URL of the API service.
+     * - forceDemoLabel Whether to force "Powered by CKBox" link.
+     * - dialog.onClose The callback function invoked after closing the CKBox dialog.
+     * - assets.onChoose The callback function invoked after choosing the assets.
+     */
+    private _prepareOptions;
+    /**
+     * Initializes various event listeners for the `ckbox:*` events, because all functionality of the `ckbox` command is event-based.
+     */
+    private _initListeners;
+    /**
+     * Inserts the asset into the model.
+     *
+     * @param asset The asset to be inserted.
+     * @param isLastAsset Indicates if the current asset is the last one from the chosen set.
+     * @param writer An instance of the model writer.
+     * @param isSingleAsset It's true when only one asset is processed.
+     */
+    private _insertAsset;
+    /**
+     * Inserts the image by calling the `insertImage` command.
+     *
+     * @param asset The asset to be inserted.
+     */
+    private _insertImage;
+    /**
+     * Inserts the link to the asset by calling the `link` command.
+     *
+     * @param asset The asset to be inserted.
+     * @param writer An instance of the model writer.
+     * @param isSingleAsset It's true when only one asset is processed.
+     */
+    private _insertLink;
+}
+/**
+ * Parses the assets attributes into the internal data format.
+ *
+ * @internal
+ */
+export declare function prepareImageAssetAttributes(asset: CKBoxRawAssetDefinition): CKBoxAssetImageAttributesDefinition;

package/dist/types/ckboxconfig.d.ts

@@ -0,0 +1,325 @@
+/**
+ * @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 ckbox/ckboxconfig
+ */
+import type { TokenUrl } from '@ckeditor/ckeditor5-cloud-services';
+import type { ArrayOrItem } from 'ckeditor5/src/utils.js';
+/**
+ * The configuration of the {@link module:ckbox/ckbox~CKBox CKBox feature}.
+ *
+ * The minimal configuration for the CKBox feature requires providing the
+ * {@link module:ckbox/ckboxconfig~CKBoxConfig#tokenUrl `config.ckbox.tokenUrl`}:
+ *
+ * ```ts
+ * ClassicEditor
+ * 	.create( editorElement, {
+ * 		ckbox: {
+ * 			tokenUrl: 'https://example.com/cs-token-endpoint'
+ * 		}
+ * 	} )
+ * 	.then( ... )
+ * 	.catch( ... );
+ * ```
+ *
+ * Hovewer, you can also adjust the feature to fit your needs:
+ *
+ * ```ts
+ * ClassicEditor
+ * 	.create( editorElement, {
+ * 		ckbox: {
+ * 			defaultUploadCategories: {
+ * 				Bitmaps: [ 'bmp' ],
+ * 				Pictures: [ 'jpg', 'jpeg' ],
+ * 				Scans: [ 'png', 'tiff' ]
+ * 			},
+ * 			ignoreDataId: true,
+ * 			serviceOrigin: 'https://example.com/',
+ * 			tokenUrl: 'https://example.com/cs-token-endpoint'
+ * 		}
+ * 	} )
+ * 	.then( ... )
+ * 	.catch( ... );
+ * ```
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ */
+export interface CKBoxConfig {
+    /**
+     * The authentication token URL for CKBox feature.
+     *
+     * Defaults to {@link module:cloud-services/cloudservicesconfig~CloudServicesConfig#tokenUrl `config.cloudServices.tokenUrl`}
+     */
+    tokenUrl?: TokenUrl;
+    /**
+     * The theme for CKBox dialog.
+     */
+    theme?: string;
+    /**
+     * Defines the categories to which the uploaded images will be assigned.
+     * If configured, it overrides the category mappings defined on the cloud service.
+     * The value of this option should be an object, where the keys define categories and their values are the types of images
+     * that will be uploaded to these categories. The categories might be referenced by their name or ID.
+     *
+     * Example:
+     *
+     * ```ts
+     * const ckboxConfig = {
+     * 	defaultUploadCategories: {
+     * 		Bitmaps: [ 'bmp' ],
+     * 		Pictures: [ 'jpg', 'jpeg' ],
+     * 		Scans: [ 'png', 'tiff' ],
+     * 		// The category below is referenced by its ID.
+     * 		'fdf2a647-b67f-4a6c-b692-5ba1dc1ed87b': [ 'gif' ]
+     * 	}
+     * };
+     * ```
+     *
+     * @default null
+     */
+    defaultUploadCategories?: Record<string, Array<string>> | null;
+    /**
+     * Defines the workspace id to use during upload when the user has access to more than one workspace.
+     *
+     * If defined, it is an error, when the user has no access to the specified workspace.
+     */
+    defaultUploadWorkspaceId?: string;
+    /**
+     * Enforces displaying the "Powered by CKBox" link regardless of the CKBox plan used.
+     */
+    forceDemoLabel?: boolean;
+    /**
+     * Allows editing images that are not hosted in CKBox service.
+     *
+     * This configuration option should whitelist URL(s) of images that should be editable.
+     * Make sure that allowed image resources have CORS enabled.
+     *
+     * The image is editable if this option is:
+     * * a regular expression and it matches the image URL, or
+     * * a custom function that returns `true` for the image URL, or
+     * * `'origin'` literal and the image URL is from the same origin, or
+     * * an array of the above and the image URL matches one of the array elements.
+     *
+     * Images hosted in CKBox are always editable.
+     *
+     * @default []
+     */
+    allowExternalImagesEditing?: ArrayOrItem<RegExp | 'origin' | ((src: string) => boolean)>;
+    /**
+     * Inserts the unique asset ID as the `data-ckbox-resource-id` attribute. To disable this behavior, set it to `true`.
+     *
+     * @default false
+     */
+    ignoreDataId?: boolean;
+    /**
+     * Configures the base URL of the API service. Required only in on-premises installations.
+     *
+     * @default 'https://api.ckbox.io'
+     */
+    serviceOrigin?: string;
+    /**
+     * Configures the language for the CKBox dialog.
+     *
+     * Defaults to {@link module:utils/locale~Locale#uiLanguage `Locale#uiLanguage`}
+     */
+    language?: string;
+}
+/**
+ * Asset definition.
+ *
+ * The definition contains the unique `id`, asset `type` and an `attributes` definition.
+ */
+export type CKBoxAssetDefinition = CKBoxAssetImageDefinition | CKBoxAssetLinkDefinition;
+/**
+ * Image asset definition.
+ *
+ * The definition contains the unique `id`, asset `type` and an `attributes` definition.
+ */
+export interface CKBoxAssetImageDefinition {
+    /**
+     * An unique asset id.
+     */
+    id: string;
+    /**
+     * Asset type.
+     */
+    type: 'image';
+    /**
+     * Asset attributes.
+     */
+    attributes: CKBoxAssetImageAttributesDefinition;
+}
+/**
+ * Link asset definition.
+ *
+ * The definition contains the unique `id`, asset `type` and an `attributes` definition.
+ */
+export interface CKBoxAssetLinkDefinition {
+    /**
+     * An unique asset id.
+     */
+    id: string;
+    /**
+     * Asset type.
+     */
+    type: 'link';
+    /**
+     * Asset attributes.
+     */
+    attributes: CKBoxAssetLinkAttributesDefinition;
+}
+/**
+ * Asset attributes definition for an image.
+ *
+ * The definition contains the `imageFallbackUrl`, an `imageSources` array with one image source definition object and the
+ * `imageTextAlternative`.
+ *
+ * ```ts
+ * {
+ * 	imageFallbackUrl: 'https://example.com/assets/asset-id/images/1000.png',
+ * 	imageSources: [
+ * 		{
+ * 			sizes: '1000px',
+ * 			srcset:
+ * 				'https://example.com/assets/asset-id/images/100.webp 100w,' +
+ * 				'https://example.com/assets/asset-id/images/200.webp 200w,' +
+ * 				'https://example.com/assets/asset-id/images/300.webp 300w,' +
+ * 				'https://example.com/assets/asset-id/images/400.webp 400w,' +
+ * 				'https://example.com/assets/asset-id/images/500.webp 500w,' +
+ * 				'https://example.com/assets/asset-id/images/600.webp 600w,' +
+ * 				'https://example.com/assets/asset-id/images/700.webp 700w,' +
+ * 				'https://example.com/assets/asset-id/images/800.webp 800w,' +
+ * 				'https://example.com/assets/asset-id/images/900.webp 900w,' +
+ * 				'https://example.com/assets/asset-id/images/1000.webp 1000w',
+ * 			type: 'image/webp'
+ * 		}
+ * 	],
+ * 	imageTextAlternative: 'An alternative text for the image'
+ * }
+ * ```
+ */
+export interface CKBoxAssetImageAttributesDefinition {
+    /**
+     * A fallback URL for browsers that do not support the "webp" format.
+     */
+    imageFallbackUrl: string;
+    /**
+     * An array containing one image source definition object.
+     */
+    imageSources: Array<{
+        srcset: string;
+        sizes: string;
+        type: string;
+    }>;
+    /**
+     * An alternative text for an image.
+     */
+    imageTextAlternative: string;
+    /**
+     * Image width.
+     */
+    imageWidth?: number;
+    /**
+     * Image height.
+     */
+    imageHeight?: number;
+    /**
+     * Image placeholder image.
+     */
+    imagePlaceholder?: string;
+}
+/**
+ * Asset attributes definition for a link.
+ *
+ * The definition contains the `linkName` and `linkHref` strings.
+ *
+ * ```ts
+ * {
+ * 	linkName: 'File name',
+ * 	linkHref: 'https://example.com/assets/asset-id/file.pdf'
+ * }
+ * ```
+ */
+export interface CKBoxAssetLinkAttributesDefinition {
+    /**
+     * A link name.
+     */
+    linkName: string;
+    /**
+     * An URL for the asset.
+     */
+    linkHref: string;
+}
+/**
+ * The source set of the responsive image provided by the CKBox backend.
+ *
+ * Each numeric key corresponds to display width of the image.
+ */
+export interface CKBoxImageUrls {
+    [width: number]: string;
+    /**
+     * A fallback URL for browsers that do not support the "webp" format.
+     */
+    default: string;
+}
+/**
+ * Raw asset definition that is received from the CKBox feature.
+ */
+export interface CKBoxRawAssetDefinition {
+    /**
+     * A raw asset data definition.
+     */
+    data: CKBoxRawAssetDataDefinition;
+}
+/**
+ * Part of raw asset data that is received from the CKBox feature.
+ */
+export interface CKBoxRawAssetDataDefinition {
+    /**
+     *  An unique asset id.
+     */
+    id: string;
+    /**
+     * An asset name.
+     */
+    name: string;
+    /**
+     *  A raw asset metadata definition.
+     */
+    metadata?: CKBoxRawAssetMetadataDefinition;
+    /**
+     * The source set of the responsive image.
+     */
+    imageUrls?: CKBoxImageUrls;
+    /**
+     * The asset location.
+     */
+    url: string;
+}
+/**
+ * Part of raw asset data that is received from the CKBox feature. Properties are set only if the chosen asset is an image.
+ */
+export interface CKBoxRawAssetMetadataDefinition {
+    /**
+     * Image description.
+     */
+    description?: string;
+    /**
+     * Image width.
+     */
+    width?: number;
+    /**
+     * Image height.
+     */
+    height?: number;
+    /**
+     * The blurhash placeholder value.
+     */
+    blurHash?: string;
+    /**
+     * The processing status of the asset.
+     */
+    metadataProcessingStatus?: string;
+}

package/dist/types/ckboxediting.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @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 CKBoxUploadAdapter from './ckboxuploadadapter.js';
+import CKBoxUtils from './ckboxutils.js';
+/**
+ * The CKBox editing feature. It introduces the {@link module:ckbox/ckboxcommand~CKBoxCommand CKBox command} and
+ * {@link module:ckbox/ckboxuploadadapter~CKBoxUploadAdapter CKBox upload adapter}.
+ */
+export default class CKBoxEditing extends Plugin {
+    /**
+     * CKEditor Cloud Services access token.
+     */
+    private _token;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "CKBoxEditing";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly ["LinkEditing", "PictureEditing", typeof CKBoxUploadAdapter, typeof CKBoxUtils];
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    afterInit(): void;
+    /**
+     * Returns true only when the integrator intentionally wants to use the plugin, i.e. when the `config.ckbox` exists or
+     * the CKBox JavaScript library is loaded.
+     */
+    private _shouldBeInitialised;
+    /**
+     * Checks if at least one image plugin is loaded.
+     */
+    private _checkImagePlugins;
+    /**
+     * Extends the schema to allow the `ckboxImageId` and `ckboxLinkId` attributes for links and images.
+     */
+    private _initSchema;
+    /**
+     * Configures the upcast and downcast conversions for the `ckboxImageId` and `ckboxLinkId` attributes.
+     */
+    private _initConversion;
+    /**
+     * Registers post-fixers that add or remove the `ckboxLinkId` and `ckboxImageId` attributes.
+     */
+    private _initFixers;
+}

package/dist/types/ckboximageedit/ckboximageeditcommand.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @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 ckbox/ckboximageedit/ckboximageeditcommand
+ */
+import { Command, type Editor } from 'ckeditor5/src/core.js';
+/**
+ * The CKBox edit image command.
+ *
+ * Opens the CKBox dialog for editing the image.
+ */
+export default class CKBoxImageEditCommand extends Command {
+    /**
+     * Flag indicating whether the command is active, i.e. dialog is open.
+     */
+    value: boolean;
+    /**
+     * The DOM element that acts as a mounting point for the CKBox Edit Image dialog.
+     */
+    private _wrapper;
+    /**
+     * The states of image processing in progress.
+     */
+    private _processInProgress;
+    /**
+     * Determines if the element can be edited.
+     */
+    private _canEdit;
+    /**
+     * A wrapper function to prepare mount options. Ensures that at most one preparation is in-flight.
+     */
+    private _prepareOptions;
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Opens the CKBox Image Editor dialog for editing the image.
+     */
+    execute(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Indicates if the CKBox Image Editor dialog is already opened.
+     */
+    private _getValue;
+    /**
+     * Creates the options object for the CKBox Image Editor dialog.
+     */
+    private _prepareOptionsAbortable;
+    /**
+     * Initializes event lister for an event of removing an image.
+     */
+    private _prepareListeners;
+    /**
+     * Gets processing states of images that have been deleted in the mean time.
+     */
+    private _getProcessingStatesOfDeletedImages;
+    private _checkIfElementIsBeingProcessed;
+    /**
+     * Closes the CKBox Image Editor dialog.
+     */
+    private _handleImageEditorClose;
+    /**
+     * Save edited image. In case server respond with "success" replace with edited image,
+     * otherwise show notification error.
+     */
+    private _handleImageEditorSave;
+    /**
+     * Get asset's status on server. If server responds with "success" status then
+     * image is already proceeded and ready for saving.
+     */
+    private _getAssetStatusFromServer;
+    /**
+     * Waits for an asset to be processed.
+     * It retries retrieving asset status from the server in case of failure.
+     */
+    private _waitForAssetProcessed;
+    /**
+     * Shows processing indicator while image is processing.
+     *
+     * @param asset Data about certain asset.
+     */
+    private _showImageProcessingIndicator;
+    /**
+     * Replace the edited image with the new one.
+     */
+    private _replaceImage;
+}

package/dist/types/ckboximageedit/ckboximageeditediting.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
+ */
+/**
+ * @module ckbox/ckboximageedit/ckboximageeditediting
+ */
+import { PendingActions, Plugin } from 'ckeditor5/src/core.js';
+import { Notification } from 'ckeditor5/src/ui.js';
+import CKBoxEditing from '../ckboxediting.js';
+import CKBoxUtils from '../ckboxutils.js';
+/**
+ * The CKBox image edit editing plugin.
+ */
+export default class CKBoxImageEditEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "CKBoxImageEditEditing";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof CKBoxEditing, typeof CKBoxUtils, typeof PendingActions, typeof Notification, "ImageUtils", "ImageEditing"];
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}