@ckeditor/ckeditor5-restricted-editing 41.3.1 → 41.4.0

package/dist/types/restrictededitingmodeediting.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @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
+ */
+/**
+ * @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 restricted-editing/restrictededitingmodeediting
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+/**
+ * The restricted editing mode editing feature.
+ *
+ * * It introduces the exception marker group that renders to `<span>` elements with the `restricted-editing-exception` CSS class.
+ * * It registers the `'goToPreviousRestrictedEditingException'` and `'goToNextRestrictedEditingException'` commands.
+ * * It also enables highlighting exception markers that are selected.
+ */
+export default class RestrictedEditingModeEditing extends Plugin {
+    /**
+     * Command names that are enabled outside the non-restricted regions.
+     */
+    private _alwaysEnabled;
+    /**
+     * Commands allowed in non-restricted areas.
+     *
+     * Commands always enabled combine typing feature commands: `'input'`, `'insertText'`, `'delete'`, and `'deleteForward'` with
+     * commands defined in the feature configuration.
+     */
+    private _allowedInException;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "RestrictedEditingModeEditing";
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Makes the given command always enabled in the restricted editing mode (regardless
+     * of selection location).
+     *
+     * To enable some commands in non-restricted areas of the content use
+     * {@link module:restricted-editing/restrictededitingconfig~RestrictedEditingConfig#allowedCommands} configuration option.
+     *
+     * @param commandName Name of the command to enable.
+     */
+    enableCommand(commandName: string): void;
+    /**
+     * Sets up the restricted mode editing conversion:
+     *
+     * * ucpast & downcast converters,
+     * * marker highlighting in the edting area,
+     * * marker post-fixers.
+     */
+    private _setupConversion;
+    /**
+     * Setups additional editing restrictions beyond command toggling:
+     *
+     * * delete content range trimming
+     * * disabling input command outside exception marker
+     * * restricting clipboard holder to text only
+     * * restricting text attributes in content
+     */
+    private _setupRestrictions;
+    /**
+     * Sets up the command toggling which enables or disables commands based on the user selection.
+     */
+    private _setupCommandsToggling;
+    /**
+     * Checks if commands should be enabled or disabled based on the current selection.
+     */
+    private _checkCommands;
+    /**
+     * Enables commands in non-restricted regions.
+     */
+    private _enableCommands;
+    /**
+     * Disables commands outside non-restricted regions.
+     */
+    private _disableCommands;
+}

package/dist/types/restrictededitingmodenavigationcommand.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @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
+ */
+/**
+ * @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';
+/**
+ * The command that allows navigation across the exceptions in the edited document.
+ */
+export default class RestrictedEditingModeNavigationCommand extends Command {
+    /**
+     * The direction of the command.
+     */
+    private _direction;
+    /**
+     * Creates an instance of the command.
+     *
+     * @param editor The editor instance.
+     * @param direction The direction that the command works.
+     */
+    constructor(editor: Editor, direction: RestrictedEditingModeNavigationDirection);
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command.
+     *
+     * @fires execute
+     */
+    execute(): void;
+    /**
+     * Checks whether the command can be enabled in the current context.
+     *
+     * @returns Whether the command should be enabled.
+     */
+    private _checkEnabled;
+}
+/**
+ * Directions in which the
+ * {@link module:restricted-editing/restrictededitingmodenavigationcommand~RestrictedEditingModeNavigationCommand} can work.
+ */
+export type RestrictedEditingModeNavigationDirection = 'forward' | 'backward';

package/dist/types/restrictededitingmodeui.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @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
+ */
+/**
+ * @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 restricted-editing/restrictededitingmodeui
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+/**
+ * The restricted editing mode UI feature.
+ *
+ * It introduces the `'restrictedEditing'` dropdown that offers tools to navigate between exceptions across
+ * the document.
+ */
+export default class RestrictedEditingModeUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "RestrictedEditingModeUI";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Creates a button for restricted editing command to use in menu bar.
+     */
+    private _createMenuBarButton;
+    /**
+     * Returns a definition of the navigation button to be used in the dropdown.
+     *
+     * @param commandName The name of the command that the button represents.
+     * @param label The translated label of the button.
+     * @param keystroke The button keystroke.
+     */
+    private _getButtonDefinition;
+    /**
+     * Returns definitions for UI buttons.
+     *
+     * @internal
+     */
+    private _getButtonDefinitions;
+}

package/dist/types/standardeditingmode.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @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
+ */
+/**
+ * @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 restricted-editing/standardeditingmode
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import StandardEditingModeEditing from './standardeditingmodeediting.js';
+import StandardEditingModeUI from './standardeditingmodeui.js';
+import '../theme/restrictedediting.css';
+/**
+ * The standard editing mode plugin.
+ *
+ * This is a "glue" plugin that loads the following plugins:
+ *
+ * * The {@link module:restricted-editing/standardeditingmodeediting~StandardEditingModeEditing standard mode editing feature}.
+ * * The {@link module:restricted-editing/standardeditingmodeui~StandardEditingModeUI standard mode UI feature}.
+ */
+export default class StandardEditingMode extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "StandardEditingMode";
+    static get requires(): readonly [typeof StandardEditingModeEditing, typeof StandardEditingModeUI];
+}

package/dist/types/standardeditingmodeediting.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @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
+ */
+/**
+ * @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 restricted-editing/standardeditingmodeediting
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+/**
+ * The standard editing mode editing feature.
+ *
+ * * It introduces the `restrictedEditingException` text attribute that is rendered as
+ * a `<span>` element with the `restricted-editing-exception` CSS class.
+ * * It registers the `'restrictedEditingException'` command.
+ */
+export default class StandardEditingModeEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "StandardEditingModeEditing";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/dist/types/standardeditingmodeui.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @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
+ */
+/**
+ * @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 restricted-editing/standardeditingmodeui
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+/**
+ * The standard editing mode UI feature.
+ *
+ * It introduces the `'restrictedEditingException'` button that marks text as unrestricted for editing.
+ */
+export default class StandardEditingModeUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "StandardEditingModeUI";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Creates a button for restricted editing exception command to use either in toolbar or in menu bar.
+     */
+    private _createButton;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-restricted-editing",
-  "version": "41.3.1",
+  "version": "41.4.0",
   "description": "Restricted editing feature for CKEditor 5 editors.",
   "keywords": [
     "ckeditor",
@@ -12,7 +12,7 @@
   "type": "module",
   "main": "src/index.js",
   "dependencies": {
-    "ckeditor5": "41.3.1"
+    "ckeditor5": "41.4.0"
   },
   "author": "CKSource (http://cksource.com/)",
   "license": "GPL-2.0-or-later",
@@ -24,6 +24,7 @@
     "directory": "packages/ckeditor5-restricted-editing"
   },
   "files": [
+    "dist",
     "lang",
     "src/**/*.js",
     "src/**/*.d.ts",

package/src/restrictededitingmodeediting.js

@@ -50,8 +50,18 @@ export default class RestrictedEditingModeEditing extends Plugin {
         // Commands & keystrokes that allow navigation in the content.
         editor.commands.add('goToPreviousRestrictedEditingException', new RestrictedEditingModeNavigationCommand(editor, 'backward'));
         editor.commands.add('goToNextRestrictedEditingException', new RestrictedEditingModeNavigationCommand(editor, 'forward'));
-        editor.keystrokes.set('Tab', getCommandExecuter(editor, 'goToNextRestrictedEditingException'));
-        editor.keystrokes.set('Shift+Tab', getCommandExecuter(editor, 'goToPreviousRestrictedEditingException'));
+        this.listenTo(editingView.document, 'tab', (evt, data) => {
+            const commandName = !data.shiftKey ? 'goToNextRestrictedEditingException' : 'goToPreviousRestrictedEditingException';
+            const command = editor.commands.get(commandName);
+            if (command.isEnabled) {
+                editor.execute(commandName);
+                // Stop the event in the DOM: no listener in the web page will be triggered by this event.
+                data.preventDefault();
+                data.stopPropagation();
+            }
+            // Stop the event bubbling in the editor: no more callbacks will be executed for this keystroke.
+            evt.stop();
+        }, { context: '$capture' });
         editor.keystrokes.set('Ctrl+A', getSelectAllHandler(editor));
         editingView.change(writer => {
             for (const root of editingView.document.roots) {
@@ -98,8 +108,43 @@ export default class RestrictedEditingModeEditing extends Plugin {
             }
         }));
         // Currently the marker helpers are tied to other use-cases and do not render a collapsed marker as highlight.
-        // That's why there are 2 downcast converters for them:
-        // 1. The default marker-to-highlight will wrap selected text with `<span>`.
+        // Also, markerToHighlight can not convert marker on an inline object. It handles only text and widgets,
+        // but it is not a case in the data pipeline. That's why there are 3 downcast converters for them:
+        //
+        // 1. The custom inline item (text or inline object) converter (but not the selection).
+        editor.conversion.for('downcast').add(dispatcher => {
+            dispatcher.on('addMarker:restrictedEditingException', (evt, data, conversionApi) => {
+                // Only convert per-item conversion.
+                if (!data.item) {
+                    return;
+                }
+                // Do not convert the selection or non-inline items.
+                if (data.item.is('selection') || !conversionApi.schema.isInline(data.item)) {
+                    return;
+                }
+                if (!conversionApi.consumable.consume(data.item, evt.name)) {
+                    return;
+                }
+                const viewWriter = conversionApi.writer;
+                const viewElement = viewWriter.createAttributeElement('span', {
+                    class: 'restricted-editing-exception'
+                }, {
+                    id: data.markerName,
+                    priority: -10
+                });
+                const viewRange = conversionApi.mapper.toViewRange(data.range);
+                const rangeAfterWrap = viewWriter.wrap(viewRange, viewElement);
+                for (const element of rangeAfterWrap.getItems()) {
+                    if (element.is('attributeElement') && element.isSimilar(viewElement)) {
+                        conversionApi.mapper.bindElementToMarker(element, data.markerName);
+                        // One attribute element is enough, because all of them are bound together by the view writer.
+                        // Mapper uses this binding to get all the elements no matter how many of them are registered in the mapper.
+                        break;
+                    }
+                }
+            });
+        });
+        // 2. The marker-to-highlight converter for the document selection.
         editor.conversion.for('downcast').markerToHighlight({
             model: 'restrictedEditingException',
             // Use callback to return new object every time new marker instance is created - otherwise it will be seen as the same marker.
@@ -111,8 +156,8 @@ export default class RestrictedEditingModeEditing extends Plugin {
                 };
             }
         });
-        // 2. But for collapsed marker we need to render it as an element.
-        // Additionally the editing pipeline should always display a collapsed marker.
+        // 3. And for collapsed marker we need to render it as an element.
+        // Additionally, the editing pipeline should always display a collapsed marker.
         editor.conversion.for('editingDowncast').markerToElement({
             model: 'restrictedEditingException',
             view: (markerData, { writer }) => {
@@ -231,18 +276,6 @@ export default class RestrictedEditingModeEditing extends Plugin {
         }
     }
 }
-/**
- * Helper method for executing enabled commands only.
- */
-function getCommandExecuter(editor, commandName) {
-    return (_, cancel) => {
-        const command = editor.commands.get(commandName);
-        if (command.isEnabled) {
-            editor.execute(commandName);
-            cancel();
-        }
-    };
-}
 /**
  * Helper for handling Ctrl+A keydown behaviour.
  */

package/src/restrictededitingmodeui.js

@@ -34,7 +34,9 @@ export default class RestrictedEditingModeUI extends Plugin {
             this._getButtonDefinitions().forEach(({ commandName, label, keystroke }) => {
                 listItems.add(this._getButtonDefinition(commandName, label, keystroke));
             });
-            addListToDropdown(dropdownView, listItems);
+            addListToDropdown(dropdownView, listItems, {
+                role: 'menu'
+            });
             dropdownView.buttonView.set({
                 label: t('Navigate editable regions'),
                 icon: lockIcon,
@@ -109,6 +111,7 @@ export default class RestrictedEditingModeUI extends Plugin {
                 withText: true,
                 keystroke,
                 withKeystroke: true,
+                role: 'menuitem',
                 _commandName: commandName
             })
         };