@ckeditor/ckeditor5-clipboard 0.0.0-nightly-20240324.0 → 0.0.0-nightly-20240326.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-clipboard",
-  "version": "0.0.0-nightly-20240324.0",
+  "version": "0.0.0-nightly-20240326.0",
   "description": "Clipboard integration feature for CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -13,11 +13,11 @@
   "type": "module",
   "main": "src/index.js",
   "dependencies": {
-    "@ckeditor/ckeditor5-core": "0.0.0-nightly-20240324.0",
-    "@ckeditor/ckeditor5-engine": "0.0.0-nightly-20240324.0",
-    "@ckeditor/ckeditor5-ui": "0.0.0-nightly-20240324.0",
-    "@ckeditor/ckeditor5-utils": "0.0.0-nightly-20240324.0",
-    "@ckeditor/ckeditor5-widget": "0.0.0-nightly-20240324.0",
+    "@ckeditor/ckeditor5-core": "0.0.0-nightly-20240326.0",
+    "@ckeditor/ckeditor5-engine": "0.0.0-nightly-20240326.0",
+    "@ckeditor/ckeditor5-ui": "0.0.0-nightly-20240326.0",
+    "@ckeditor/ckeditor5-utils": "0.0.0-nightly-20240326.0",
+    "@ckeditor/ckeditor5-widget": "0.0.0-nightly-20240326.0",
     "lodash-es": "4.17.21"
   },
   "author": "CKSource (http://cksource.com/)",

package/src/clipboardmarkersutils.d.ts

@@ -2,8 +2,8 @@
  * @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 '@ckeditor/ckeditor5-core';
-import { Range, type Element, type DocumentFragment, type DocumentSelection, type Selection, type Writer } from '@ckeditor/ckeditor5-engine';
+import { Plugin, type NonEmptyArray } from '@ckeditor/ckeditor5-core';
+import { Range, type DocumentFragment, type Element, type DocumentSelection, type Selection, type Writer } from '@ckeditor/ckeditor5-engine';
 /**
  * Part of the clipboard logic. Responsible for collecting markers from selected fragments
  * and restoring them with proper positions in pasted elements.
@@ -25,17 +25,10 @@ export default class ClipboardMarkersUtils extends Plugin {
      * Registers marker name as copyable in clipboard pipeline.
      *
      * @param markerName Name of marker that can be copied.
-     * @param restrictions Preset or specified array of actions that can be performed on specified marker name.
+     * @param config Configuration that describes what can be performed on specified marker.
      * @internal
      */
-    _registerMarkerToCopy(markerName: string, restrictions: ClipboardMarkerRestrictionsPreset | Array<ClipboardMarkerRestrictedAction>): void;
-    /**
-     * Maps preset into array of clipboard operations to be allowed on marker.
-     *
-     * @param preset Restrictions preset to be mapped to actions
-     * @internal
-     */
-    private _mapRestrictionPresetToActions;
+    _registerMarkerToCopy(markerName: string, config: ClipboardMarkerConfiguration): void;
     /**
      * Performs copy markers on provided selection and paste it to fragment returned from `getCopiedFragment`.
      *
@@ -67,6 +60,7 @@ export default class ClipboardMarkersUtils extends Plugin {
      *
      * 	* `markers` are inserted into the same element that must be later transformed inside `getPastedDocumentElement`.
      * 	* Fake marker elements inside `getPastedDocumentElement` can be cloned, but their ranges cannot overlap.
+     * 	* If `duplicateOnPaste` is `true` in marker config then associated marker ID is regenerated before pasting.
      *
      * @param action Type of clipboard action.
      * @param markers Object that maps marker name to corresponding range.
@@ -74,6 +68,15 @@ export default class ClipboardMarkersUtils extends Plugin {
      * @internal
      */
     _pasteMarkersIntoTransformedElement(markers: Record<string, Range> | Map<string, Range>, getPastedDocumentElement: (writer: Writer) => Element): Element;
+    /**
+     * Pastes document fragment with markers to document.
+     * If `duplicateOnPaste` is `true` in marker config then associated markers IDs
+     * are regenerated before pasting to avoid markers duplications in content.
+     *
+     * @param fragment Document fragment that should contain already processed by pipeline markers.
+     * @internal
+     */
+    _pasteFragmentWithMarkers(fragment: DocumentFragment): Range;
     /**
      * In some situations we have to perform copy on selected fragment with certain markers. This function allows to temporarily bypass
      * restrictions on markers that we want to copy.
@@ -83,9 +86,10 @@ export default class ClipboardMarkersUtils extends Plugin {
      *
      * @param markerName Which markers should be copied.
      * @param executor Callback executed.
+     * @param config Optional configuration flags used to copy (such like partial copy flag).
      * @internal
      */
-    _forceMarkersCopy(markerName: string, executor: VoidFunction): void;
+    _forceMarkersCopy(markerName: string, executor: VoidFunction, config?: ClipboardMarkerConfiguration): void;
     /**
      * Checks if marker can be copied.
      *
@@ -93,14 +97,20 @@ export default class ClipboardMarkersUtils extends Plugin {
      * @param action Type of clipboard action. If null then checks only if marker is registered as copyable.
      * @internal
      */
-    _canPerformMarkerClipboardAction(markerName: string, action: ClipboardMarkerRestrictedAction | null): boolean;
+    _isMarkerCopyable(markerName: string, action: ClipboardMarkerRestrictedAction | null): boolean;
     /**
-     * Changes marker names for markers stored in given document fragment so that they are unique.
+     * Checks if marker has any clipboard copy behavior configuration.
      *
-     * @param fragment
+     * @param markerName Name of checked marker.
+     */
+    _hasMarkerConfiguration(markerName: string): boolean;
+    /**
+     * Returns marker's configuration flags passed during registration.
+     *
+     * @param markerName Name of marker that should be returned.
      * @internal
      */
-    _setUniqueMarkerNamesInFragment(fragment: DocumentFragment): void;
+    _getMarkerClipboardConfig(markerName: string): ClipboardMarkerConfiguration | null;
     /**
      * First step of copying markers. It looks for markers intersecting with given selection and inserts `$marker` elements
      * at positions where document markers start or end. This way `$marker` elements can be easily copied together with
@@ -114,18 +124,23 @@ export default class ClipboardMarkersUtils extends Plugin {
     /**
      * Returns array of markers that can be copied in specified selection.
      *
+     * If marker cannot be copied partially (according to `copyPartiallySelected` configuration flag) and
+     * is not present entirely in any selection range then it will be skipped.
+     *
      * @param writer An instance of the model writer.
      * @param selection  Selection which will be checked.
      * @param action Type of clipboard action. If null then checks only if marker is registered as copyable.
      */
     private _getCopyableMarkersFromSelection;
     /**
-     * Picks all markers from markers map that can be copied.
+     * Picks all markers from markers map that can be pasted.
+     * If `duplicateOnPaste` is `true`, it regenerates their IDs to ensure uniqueness.
+     * If marker is not registered, it will be kept in the array anyway.
      *
      * @param markers Object that maps marker name to corresponding range.
      * @param action Type of clipboard action. If null then checks only if marker is registered as copyable.
      */
-    private _getCopyableMarkersFromRangeMap;
+    private _getPasteMarkersFromRangeMap;
     /**
      * Inserts specified array of fake markers elements to document and assigns them `type` and `name` attributes.
      * Fake markers elements are used to calculate position of markers on pasted fragment that were transformed during
@@ -174,13 +189,12 @@ export default class ClipboardMarkersUtils extends Plugin {
  */
 export type ClipboardMarkerRestrictedAction = 'copy' | 'cut' | 'dragstart';
 /**
- * Specifies copy, paste or move marker restrictions in clipboard. Depending on specified mode
- * it will disallow copy, cut or paste of marker in clipboard.
- *
- * 	* `'default'` - the markers will be preserved on cut-paste and drag and drop actions only.
- * 	* `'always'` - the markers will be preserved on all clipboard actions (cut, copy, drag and drop).
- * 	* `'never'` - the markers will be ignored by clipboard.
+ * Specifies behavior of markers during clipboard actions.
  *
  * @internal
  */
-export type ClipboardMarkerRestrictionsPreset = 'default' | 'always' | 'never';
+export type ClipboardMarkerConfiguration = {
+    allowedActions: NonEmptyArray<ClipboardMarkerRestrictedAction> | 'all';
+    copyPartiallySelected?: boolean;
+    duplicateOnPaste?: boolean;
+};

package/src/clipboardmarkersutils.js

@@ -35,36 +35,11 @@ export default class ClipboardMarkersUtils extends Plugin {
      * Registers marker name as copyable in clipboard pipeline.
      *
      * @param markerName Name of marker that can be copied.
-     * @param restrictions Preset or specified array of actions that can be performed on specified marker name.
+     * @param config Configuration that describes what can be performed on specified marker.
      * @internal
      */
-    _registerMarkerToCopy(markerName, restrictions) {
-        const allowedActions = Array.isArray(restrictions) ? restrictions : this._mapRestrictionPresetToActions(restrictions);
-        if (allowedActions.length) {
-            this._markersToCopy.set(markerName, allowedActions);
-        }
-    }
-    /**
-     * Maps preset into array of clipboard operations to be allowed on marker.
-     *
-     * @param preset Restrictions preset to be mapped to actions
-     * @internal
-     */
-    _mapRestrictionPresetToActions(preset) {
-        switch (preset) {
-            case 'always':
-                return ['copy', 'cut', 'dragstart'];
-            case 'default':
-                return ['cut', 'dragstart'];
-            case 'never':
-                return [];
-            default: {
-                // Skip unrecognized type.
-                // eslint-disable-next-line @typescript-eslint/no-unused-vars
-                const unreachable = preset;
-                return [];
-            }
-        }
+    _registerMarkerToCopy(markerName, config) {
+        this._markersToCopy.set(markerName, config);
     }
     /**
      * Performs copy markers on provided selection and paste it to fragment returned from `getCopiedFragment`.
@@ -133,6 +108,7 @@ export default class ClipboardMarkersUtils extends Plugin {
      *
      * 	* `markers` are inserted into the same element that must be later transformed inside `getPastedDocumentElement`.
      * 	* Fake marker elements inside `getPastedDocumentElement` can be cloned, but their ranges cannot overlap.
+     * 	* If `duplicateOnPaste` is `true` in marker config then associated marker ID is regenerated before pasting.
      *
      * @param action Type of clipboard action.
      * @param markers Object that maps marker name to corresponding range.
@@ -140,26 +116,47 @@ export default class ClipboardMarkersUtils extends Plugin {
      * @internal
      */
     _pasteMarkersIntoTransformedElement(markers, getPastedDocumentElement) {
-        const copyableMarkers = this._getCopyableMarkersFromRangeMap(markers);
+        const pasteMarkers = this._getPasteMarkersFromRangeMap(markers);
         return this.editor.model.change(writer => {
-            const sourceFragmentFakeMarkers = this._insertFakeMarkersElements(writer, copyableMarkers);
+            // Inserts fake markers into source fragment / element that is later transformed inside `getPastedDocumentElement`.
+            const sourceFragmentFakeMarkers = this._insertFakeMarkersElements(writer, pasteMarkers);
+            // Modifies document fragment (for example, cloning table cells) and then inserts it into the document.
             const transformedElement = getPastedDocumentElement(writer);
+            // Removes markers in pasted and transformed fragment in root document.
             const removedFakeMarkers = this._removeFakeMarkersInsideElement(writer, transformedElement);
-            // Cleanup fake markers inserted into transformed element.
+            // Cleans up fake markers inserted into source fragment (that one before transformation which is not pasted).
             for (const element of Object.values(sourceFragmentFakeMarkers).flat()) {
                 writer.remove(element);
             }
+            // Inserts to root document fake markers.
             for (const [markerName, range] of Object.entries(removedFakeMarkers)) {
-                const uniqueName = writer.model.markers.has(markerName) ? this._getUniqueMarkerName(markerName) : markerName;
-                writer.addMarker(uniqueName, {
-                    usingOperation: true,
-                    affectsData: true,
-                    range
-                });
+                if (!writer.model.markers.has(markerName)) {
+                    writer.addMarker(markerName, {
+                        usingOperation: true,
+                        affectsData: true,
+                        range
+                    });
+                }
             }
             return transformedElement;
         });
     }
+    /**
+     * Pastes document fragment with markers to document.
+     * If `duplicateOnPaste` is `true` in marker config then associated markers IDs
+     * are regenerated before pasting to avoid markers duplications in content.
+     *
+     * @param fragment Document fragment that should contain already processed by pipeline markers.
+     * @internal
+     */
+    _pasteFragmentWithMarkers(fragment) {
+        const pasteMarkers = this._getPasteMarkersFromRangeMap(fragment.markers);
+        fragment.markers.clear();
+        for (const copyableMarker of pasteMarkers) {
+            fragment.markers.set(copyableMarker.name, copyableMarker.range);
+        }
+        return this.editor.model.insertContent(fragment);
+    }
     /**
      * In some situations we have to perform copy on selected fragment with certain markers. This function allows to temporarily bypass
      * restrictions on markers that we want to copy.
@@ -169,11 +166,16 @@ export default class ClipboardMarkersUtils extends Plugin {
      *
      * @param markerName Which markers should be copied.
      * @param executor Callback executed.
+     * @param config Optional configuration flags used to copy (such like partial copy flag).
      * @internal
      */
-    _forceMarkersCopy(markerName, executor) {
+    _forceMarkersCopy(markerName, executor, config = {
+        allowedActions: 'all',
+        copyPartiallySelected: true,
+        duplicateOnPaste: true
+    }) {
         const before = this._markersToCopy.get(markerName);
-        this._markersToCopy.set(markerName, this._mapRestrictionPresetToActions('always'));
+        this._markersToCopy.set(markerName, config);
         executor();
         if (before) {
             this._markersToCopy.set(markerName, before);
@@ -189,27 +191,35 @@ export default class ClipboardMarkersUtils extends Plugin {
      * @param action Type of clipboard action. If null then checks only if marker is registered as copyable.
      * @internal
      */
-    _canPerformMarkerClipboardAction(markerName, action) {
-        const [markerNamePrefix] = markerName.split(':');
+    _isMarkerCopyable(markerName, action) {
+        const config = this._getMarkerClipboardConfig(markerName);
+        if (!config) {
+            return false;
+        }
+        // If there is no action provided then only presence of marker is checked.
         if (!action) {
-            return this._markersToCopy.has(markerNamePrefix);
+            return true;
         }
-        const possibleActions = this._markersToCopy.get(markerNamePrefix) || [];
-        return possibleActions.includes(action);
+        const { allowedActions } = config;
+        return allowedActions === 'all' || allowedActions.includes(action);
+    }
+    /**
+     * Checks if marker has any clipboard copy behavior configuration.
+     *
+     * @param markerName Name of checked marker.
+     */
+    _hasMarkerConfiguration(markerName) {
+        return !!this._getMarkerClipboardConfig(markerName);
     }
     /**
-     * Changes marker names for markers stored in given document fragment so that they are unique.
+     * Returns marker's configuration flags passed during registration.
      *
-     * @param fragment
+     * @param markerName Name of marker that should be returned.
      * @internal
      */
-    _setUniqueMarkerNamesInFragment(fragment) {
-        const markers = Array.from(fragment.markers);
-        fragment.markers.clear();
-        for (const [name, range] of markers) {
-            const newName = this._canPerformMarkerClipboardAction(name, null) ? this._getUniqueMarkerName(name) : name;
-            fragment.markers.set(newName, range);
-        }
+    _getMarkerClipboardConfig(markerName) {
+        const [markerNamePrefix] = markerName.split(':');
+        return this._markersToCopy.get(markerNamePrefix) || null;
     }
     /**
      * First step of copying markers. It looks for markers intersecting with given selection and inserts `$marker` elements
@@ -227,34 +237,89 @@ export default class ClipboardMarkersUtils extends Plugin {
     /**
      * Returns array of markers that can be copied in specified selection.
      *
+     * If marker cannot be copied partially (according to `copyPartiallySelected` configuration flag) and
+     * is not present entirely in any selection range then it will be skipped.
+     *
      * @param writer An instance of the model writer.
      * @param selection  Selection which will be checked.
      * @param action Type of clipboard action. If null then checks only if marker is registered as copyable.
      */
     _getCopyableMarkersFromSelection(writer, selection, action) {
+        const selectionRanges = Array.from(selection.getRanges());
+        // Picks all markers in provided ranges. Ensures that there are no duplications if
+        // there are multiple ranges that intersects with the same marker.
+        const markersInRanges = new Set(selectionRanges.flatMap(selectionRange => Array.from(writer.model.markers.getMarkersIntersectingRange(selectionRange))));
+        const isSelectionMarkerCopyable = (marker) => {
+            // Check if marker exists in configuration and provided action can be performed on it.
+            const isCopyable = this._isMarkerCopyable(marker.name, action);
+            if (!isCopyable) {
+                return false;
+            }
+            // Checks if configuration disallows to copy marker only if part of its content is selected.
+            //
+            // Example:
+            // 	<marker-a> Hello [ World ] </marker-a>
+            //						^ selection
+            //
+            // In this scenario `marker-a` won't be copied because selection doesn't overlap its content entirely.
+            const { copyPartiallySelected } = this._getMarkerClipboardConfig(marker.name);
+            if (!copyPartiallySelected) {
+                const markerRange = marker.getRange();
+                return selectionRanges.some(selectionRange => selectionRange.containsRange(markerRange, true));
+            }
+            return true;
+        };
         return Array
-            .from(selection.getRanges())
-            .flatMap(selectionRange => Array.from(writer.model.markers.getMarkersIntersectingRange(selectionRange)))
-            .filter(marker => this._canPerformMarkerClipboardAction(marker.name, action))
-            .map((marker) => ({
-            name: marker.name,
-            range: marker.getRange()
-        }));
+            .from(markersInRanges)
+            .filter(isSelectionMarkerCopyable)
+            .map((copyableMarker) => {
+            // During `dragstart` event original marker is still present in tree.
+            // It is removed after the clipboard drop event, so none of the copied markers are inserted at the end.
+            // It happens because there already markers with specified `marker.name` when clipboard is trying to insert data
+            // and it aborts inserting.
+            const name = action === 'dragstart' ? this._getUniqueMarkerName(copyableMarker.name) : copyableMarker.name;
+            return {
+                name,
+                range: copyableMarker.getRange()
+            };
+        });
     }
     /**
-     * Picks all markers from markers map that can be copied.
+     * Picks all markers from markers map that can be pasted.
+     * If `duplicateOnPaste` is `true`, it regenerates their IDs to ensure uniqueness.
+     * If marker is not registered, it will be kept in the array anyway.
      *
      * @param markers Object that maps marker name to corresponding range.
      * @param action Type of clipboard action. If null then checks only if marker is registered as copyable.
      */
-    _getCopyableMarkersFromRangeMap(markers, action = null) {
+    _getPasteMarkersFromRangeMap(markers, action = null) {
+        const { model } = this.editor;
         const entries = markers instanceof Map ? Array.from(markers.entries()) : Object.entries(markers);
-        return entries
-            .map(([markerName, range]) => ({
-            name: markerName,
-            range
-        }))
-            .filter(marker => this._canPerformMarkerClipboardAction(marker.name, action));
+        return entries.flatMap(([markerName, range]) => {
+            if (!this._hasMarkerConfiguration(markerName)) {
+                return [
+                    {
+                        name: markerName,
+                        range
+                    }
+                ];
+            }
+            if (this._isMarkerCopyable(markerName, action)) {
+                const copyMarkerConfig = this._getMarkerClipboardConfig(markerName);
+                const isInGraveyard = model.markers.has(markerName) &&
+                    model.markers.get(markerName).getRange().root.rootName === '$graveyard';
+                if (copyMarkerConfig.duplicateOnPaste || isInGraveyard) {
+                    markerName = this._getUniqueMarkerName(markerName);
+                }
+                return [
+                    {
+                        name: markerName,
+                        range
+                    }
+                ];
+            }
+            return [];
+        });
     }
     /**
      * Inserts specified array of fake markers elements to document and assigns them `type` and `name` attributes.
@@ -314,14 +379,23 @@ export default class ClipboardMarkersUtils extends Plugin {
             //
             // The easiest way to bypass this issue is to rename already existing in map nodes and
             // set them new unique name.
+            let skipAssign = false;
             if (prevFakeMarker && prevFakeMarker.start && prevFakeMarker.end) {
-                acc[this._getUniqueMarkerName(fakeMarker.name)] = acc[fakeMarker.name];
+                const config = this._getMarkerClipboardConfig(fakeMarker.name);
+                if (config.duplicateOnPaste) {
+                    acc[this._getUniqueMarkerName(fakeMarker.name)] = acc[fakeMarker.name];
+                }
+                else {
+                    skipAssign = true;
+                }
                 prevFakeMarker = null;
             }
-            acc[fakeMarker.name] = {
-                ...prevFakeMarker,
-                [fakeMarker.type]: position
-            };
+            if (!skipAssign) {
+                acc[fakeMarker.name] = {
+                    ...prevFakeMarker,
+                    [fakeMarker.type]: position
+                };
+            }
             if (fakeMarker.markerElement) {
                 writer.remove(fakeMarker.markerElement);
             }

package/src/clipboardpipeline.js

@@ -147,11 +147,13 @@ export default class ClipboardPipeline extends Plugin {
      */
     _fireOutputTransformationEvent(dataTransfer, selection, method) {
         const clipboardMarkersUtils = this.editor.plugins.get('ClipboardMarkersUtils');
-        const documentFragment = clipboardMarkersUtils._copySelectedFragmentWithMarkers(method, selection);
-        this.fire('outputTransformation', {
-            dataTransfer,
-            content: documentFragment,
-            method
+        this.editor.model.enqueueChange({ isUndoable: method === 'cut' }, () => {
+            const documentFragment = clipboardMarkersUtils._copySelectedFragmentWithMarkers(method, selection);
+            this.fire('outputTransformation', {
+                dataTransfer,
+                content: documentFragment,
+                method
+            });
         });
     }
     /**
@@ -227,10 +229,7 @@ export default class ClipboardPipeline extends Plugin {
             });
         }, { priority: 'low' });
         this.listenTo(this, 'contentInsertion', (evt, data) => {
-            clipboardMarkersUtils._setUniqueMarkerNamesInFragment(data.content);
-        }, { priority: 'highest' });
-        this.listenTo(this, 'contentInsertion', (evt, data) => {
-            data.resultRange = model.insertContent(data.content);
+            data.resultRange = clipboardMarkersUtils._pasteFragmentWithMarkers(data.content);
         }, { priority: 'low' });
     }
     /**

package/src/index.d.ts

@@ -7,7 +7,7 @@
  */
 export { default as Clipboard } from './clipboard.js';
 export { default as ClipboardPipeline, type ClipboardContentInsertionEvent, type ClipboardContentInsertionData, type ClipboardInputTransformationEvent, type ClipboardInputTransformationData, type ClipboardOutputTransformationEvent, type ClipboardOutputTransformationData, type ViewDocumentClipboardOutputEvent } from './clipboardpipeline.js';
-export { default as ClipboardMarkersUtils, type ClipboardMarkerRestrictionsPreset, type ClipboardMarkerRestrictedAction } from './clipboardmarkersutils.js';
+export { default as ClipboardMarkersUtils, type ClipboardMarkerRestrictedAction, type ClipboardMarkerConfiguration } from './clipboardmarkersutils.js';
 export type { ClipboardEventData } from './clipboardobserver.js';
 export { default as DragDrop } from './dragdrop.js';
 export { default as PastePlainText } from './pasteplaintext.js';