@ckeditor/ckeditor5-restricted-editing 41.4.2 → 42.0.0-alpha.0

package/README.md

@@ -15,6 +15,12 @@ Check out the demo in the [restricted editing feature guide](https://ckeditor.co
 
 See the [`@ckeditor/ckeditor5-restricted-editing` package](https://ckeditor.com/docs/ckeditor5/latest/api/restricted-editing.html) page as well as the [restricted editing feature](https://ckeditor.com/docs/ckeditor5/latest/features/restricted-editing.html) guide in the [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/).
 
+## Installation
+
+```bash
+npm install ckeditor5
+```
+
 ## License
 
 Licensed under the terms of [GNU General Public License Version 2 or later](http://www.gnu.org/licenses/gpl.html). For full details about the license, please check the `LICENSE.md` file or [https://ckeditor.com/legal/ckeditor-oss-license](https://ckeditor.com/legal/ckeditor-oss-license).

package/dist/index.js

@@ -7,17 +7,33 @@ import { Matcher } from '@ckeditor/ckeditor5-engine/dist/index.js';
 import { createDropdown, addListToDropdown, MenuBarMenuView, MenuBarMenuListView, MenuBarMenuListItemView, MenuBarMenuListItemButtonView, ViewModel, ButtonView } from '@ckeditor/ckeditor5-ui/dist/index.js';
 import { Collection } from '@ckeditor/ckeditor5-utils/dist/index.js';
 
-class RestrictedEditingModeNavigationCommand extends Command {
+/**
+ * The command that allows navigation across the exceptions in the edited document.
+ */ class RestrictedEditingModeNavigationCommand extends Command {
+    /**
+	 * The direction of the command.
+	 */ _direction;
     /**
-     * @inheritDoc
-     */ refresh() {
+	 * Creates an instance of the command.
+	 *
+	 * @param editor The editor instance.
+	 * @param direction The direction that the command works.
+	 */ constructor(editor, direction){
+        super(editor);
+        // It does not affect data so should be enabled in read-only mode and in restricted editing mode.
+        this.affectsData = false;
+        this._direction = direction;
+    }
+    /**
+	 * @inheritDoc
+	 */ refresh() {
         this.isEnabled = this._checkEnabled();
     }
     /**
-     * Executes the command.
-     *
-     * @fires execute
-     */ execute() {
+	 * Executes the command.
+	 *
+	 * @fires execute
+	 */ execute() {
         const position = getNearestExceptionRange(this.editor.model, this._direction);
         if (!position) {
             return;
@@ -27,23 +43,12 @@ class RestrictedEditingModeNavigationCommand extends Command {
         });
     }
     /**
-     * Checks whether the command can be enabled in the current context.
-     *
-     * @returns Whether the command should be enabled.
-     */ _checkEnabled() {
+	 * Checks whether the command can be enabled in the current context.
+	 *
+	 * @returns Whether the command should be enabled.
+	 */ _checkEnabled() {
         return !!getNearestExceptionRange(this.editor.model, this._direction);
     }
-    /**
-     * Creates an instance of the command.
-     *
-     * @param editor The editor instance.
-     * @param direction The direction that the command works.
-     */ constructor(editor, direction){
-        super(editor);
-        // It does not affect data so should be enabled in read-only mode and in restricted editing mode.
-        this.affectsData = false;
-        this._direction = direction;
-    }
 }
 /**
  * Returns the range of the exception marker closest to the last position of the model selection.
@@ -271,15 +276,58 @@ const HIGHLIGHT_CLASS = 'restricted-editing-exception_selected';
 }
 
 const COMMAND_FORCE_DISABLE_ID = 'RestrictedEditingMode';
-class RestrictedEditingModeEditing extends Plugin {
+/**
+ * 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.
+ */ class RestrictedEditingModeEditing extends Plugin {
     /**
-     * @inheritDoc
-     */ static get pluginName() {
+	 * Command names that are enabled outside the non-restricted regions.
+	 */ _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.
+	 */ _allowedInException;
+    /**
+	 * @inheritDoc
+	 */ static get pluginName() {
         return 'RestrictedEditingModeEditing';
     }
     /**
-     * @inheritDoc
-     */ init() {
+	 * @inheritDoc
+	 */ constructor(editor){
+        super(editor);
+        editor.config.define('restrictedEditing', {
+            allowedCommands: [
+                'bold',
+                'italic',
+                'link',
+                'unlink'
+            ],
+            allowedAttributes: [
+                'bold',
+                'italic',
+                'linkHref'
+            ]
+        });
+        this._alwaysEnabled = new Set([
+            'undo',
+            'redo'
+        ]);
+        this._allowedInException = new Set([
+            'input',
+            'insertText',
+            'delete',
+            'deleteForward'
+        ]);
+    }
+    /**
+	 * @inheritDoc
+	 */ init() {
         const editor = this.editor;
         const editingView = editor.editing.view;
         const allowedCommands = editor.config.get('restrictedEditing.allowedCommands');
@@ -312,25 +360,25 @@ class RestrictedEditingModeEditing extends Plugin {
         });
     }
     /**
-     * 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) {
+	 * 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) {
         const command = this.editor.commands.get(commandName);
         command.clearForceDisabled(COMMAND_FORCE_DISABLE_ID);
         this._alwaysEnabled.add(commandName);
     }
     /**
-     * Sets up the restricted mode editing conversion:
-     *
-     * * ucpast & downcast converters,
-     * * marker highlighting in the edting area,
-     * * marker post-fixers.
-     */ _setupConversion() {
+	 * Sets up the restricted mode editing conversion:
+	 *
+	 * * ucpast & downcast converters,
+	 * * marker highlighting in the edting area,
+	 * * marker post-fixers.
+	 */ _setupConversion() {
         const editor = this.editor;
         const model = editor.model;
         const doc = model.document;
@@ -418,13 +466,13 @@ class RestrictedEditingModeEditing extends Plugin {
         setupExceptionHighlighting(editor);
     }
     /**
-     * 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
-     */ _setupRestrictions() {
+	 * 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
+	 */ _setupRestrictions() {
         const editor = this.editor;
         const model = editor.model;
         const selection = model.document.selection;
@@ -460,8 +508,8 @@ class RestrictedEditingModeEditing extends Plugin {
         model.schema.addChildCheck(allowTextOnlyInClipboardHolder());
     }
     /**
-     * Sets up the command toggling which enables or disables commands based on the user selection.
-     */ _setupCommandsToggling() {
+	 * Sets up the command toggling which enables or disables commands based on the user selection.
+	 */ _setupCommandsToggling() {
         const editor = this.editor;
         const model = editor.model;
         const doc = model.document;
@@ -470,8 +518,8 @@ class RestrictedEditingModeEditing extends Plugin {
         this.listenTo(doc, 'change:data', this._checkCommands.bind(this));
     }
     /**
-     * Checks if commands should be enabled or disabled based on the current selection.
-     */ _checkCommands() {
+	 * Checks if commands should be enabled or disabled based on the current selection.
+	 */ _checkCommands() {
         const editor = this.editor;
         const selection = editor.model.document.selection;
         if (selection.rangeCount > 1) {
@@ -485,8 +533,8 @@ class RestrictedEditingModeEditing extends Plugin {
         }
     }
     /**
-     * Enables commands in non-restricted regions.
-     */ _enableCommands(marker) {
+	 * Enables commands in non-restricted regions.
+	 */ _enableCommands(marker) {
         const editor = this.editor;
         for (const [commandName, command] of editor.commands){
             if (!command.affectsData || this._alwaysEnabled.has(commandName)) {
@@ -504,8 +552,8 @@ class RestrictedEditingModeEditing extends Plugin {
         }
     }
     /**
-     * Disables commands outside non-restricted regions.
-     */ _disableCommands() {
+	 * Disables commands outside non-restricted regions.
+	 */ _disableCommands() {
         const editor = this.editor;
         for (const [commandName, command] of editor.commands){
             if (!command.affectsData || this._alwaysEnabled.has(commandName)) {
@@ -514,34 +562,6 @@ class RestrictedEditingModeEditing extends Plugin {
             command.forceDisabled(COMMAND_FORCE_DISABLE_ID);
         }
     }
-    /**
-     * @inheritDoc
-     */ constructor(editor){
-        super(editor);
-        editor.config.define('restrictedEditing', {
-            allowedCommands: [
-                'bold',
-                'italic',
-                'link',
-                'unlink'
-            ],
-            allowedAttributes: [
-                'bold',
-                'italic',
-                'linkHref'
-            ]
-        });
-        this._alwaysEnabled = new Set([
-            'undo',
-            'redo'
-        ]);
-        this._allowedInException = new Set([
-            'input',
-            'insertText',
-            'delete',
-            'deleteForward'
-        ]);
-    }
 }
 /**
  * Helper for handling Ctrl+A keydown behaviour.
@@ -685,15 +705,20 @@ function allowTextOnlyInClipboardHolder() {
 
 var lockIcon = "<svg viewBox=\"0 0 20 20\" xmlns=\"http://www.w3.org/2000/svg\"><path d=\"M15.5 6.5a3.5 3.5 0 0 1 3.495 3.308L19 10v2a1 1 0 0 1 1 1v5a1 1 0 0 1-1 1h-7a1 1 0 0 1-1-1v-5a1 1 0 0 1 1-1v-2l.005-.192A3.5 3.5 0 0 1 15.5 6.5zm0 7.5a.5.5 0 0 0-.492.41L15 14.5v2a.5.5 0 0 0 .992.09L16 16.5v-2a.5.5 0 0 0-.5-.5zm0-6a2 2 0 0 0-2 2v2h4v-2a2 2 0 0 0-2-2zm-9.25 8a.75.75 0 1 1 0 1.5H.75a.75.75 0 1 1 0-1.5h5.5zm0-5a.75.75 0 1 1 0 1.5H.75a.75.75 0 1 1 0-1.5h5.5zm3-5a.75.75 0 0 1 0 1.5H.75a.75.75 0 0 1 0-1.5h8.5zm6-5a.75.75 0 1 1 0 1.5H.75a.75.75 0 0 1 0-1.5h14.5z\"/></svg>";
 
-class RestrictedEditingModeUI extends Plugin {
+/**
+ * The restricted editing mode UI feature.
+ *
+ * It introduces the `'restrictedEditing'` dropdown that offers tools to navigate between exceptions across
+ * the document.
+ */ class RestrictedEditingModeUI extends Plugin {
     /**
-     * @inheritDoc
-     */ static get pluginName() {
+	 * @inheritDoc
+	 */ static get pluginName() {
         return 'RestrictedEditingModeUI';
     }
     /**
-     * @inheritDoc
-     */ init() {
+	 * @inheritDoc
+	 */ init() {
         const editor = this.editor;
         const t = editor.t;
         editor.ui.componentFactory.add('restrictedEditing', (locale)=>{
@@ -742,8 +767,8 @@ class RestrictedEditingModeUI extends Plugin {
         });
     }
     /**
-     * Creates a button for restricted editing command to use in menu bar.
-     */ _createMenuBarButton(label, commandName, keystroke) {
+	 * Creates a button for restricted editing command to use in menu bar.
+	 */ _createMenuBarButton(label, commandName, keystroke) {
         const editor = this.editor;
         const command = editor.commands.get(commandName);
         const view = new MenuBarMenuListItemButtonView(editor.locale);
@@ -762,12 +787,12 @@ class RestrictedEditingModeUI extends Plugin {
         return view;
     }
     /**
-     * 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.
-     */ _getButtonDefinition(commandName, label, keystroke) {
+	 * 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.
+	 */ _getButtonDefinition(commandName, label, keystroke) {
         const editor = this.editor;
         const command = editor.commands.get(commandName);
         const definition = {
@@ -785,10 +810,10 @@ class RestrictedEditingModeUI extends Plugin {
         return definition;
     }
     /**
-     * Returns definitions for UI buttons.
-     *
-     * @internal
-     */ _getButtonDefinitions() {
+	 * Returns definitions for UI buttons.
+	 *
+	 * @internal
+	 */ _getButtonDefinitions() {
         const t = this.editor.locale.t;
         return [
             {
@@ -805,15 +830,22 @@ class RestrictedEditingModeUI extends Plugin {
     }
 }
 
-class RestrictedEditingMode extends Plugin {
+/**
+ * The restricted editing mode plugin.
+ *
+ * This is a "glue" plugin which loads the following plugins:
+ *
+ * * The {@link module:restricted-editing/restrictededitingmodeediting~RestrictedEditingModeEditing restricted mode editing feature}.
+ * * The {@link module:restricted-editing/restrictededitingmodeui~RestrictedEditingModeUI restricted mode UI feature}.
+ */ class RestrictedEditingMode extends Plugin {
     /**
-     * @inheritDoc
-     */ static get pluginName() {
+	 * @inheritDoc
+	 */ static get pluginName() {
         return 'RestrictedEditingMode';
     }
     /**
-     * @inheritDoc
-     */ static get requires() {
+	 * @inheritDoc
+	 */ static get requires() {
         return [
             RestrictedEditingModeEditing,
             RestrictedEditingModeUI
@@ -821,18 +853,20 @@ class RestrictedEditingMode extends Plugin {
     }
 }
 
-class RestrictedEditingExceptionCommand extends Command {
+/**
+ * The command that toggles exceptions from the restricted editing on text.
+ */ class RestrictedEditingExceptionCommand extends Command {
     /**
-     * @inheritDoc
-     */ refresh() {
+	 * @inheritDoc
+	 */ refresh() {
         const model = this.editor.model;
         const doc = model.document;
         this.value = !!doc.selection.getAttribute('restrictedEditingException');
         this.isEnabled = model.schema.checkAttributeInSelection(doc.selection, 'restrictedEditingException');
     }
     /**
-     * @inheritDoc
-     */ execute(options = {}) {
+	 * @inheritDoc
+	 */ execute(options = {}) {
         const model = this.editor.model;
         const document = model.document;
         const selection = document.selection;
@@ -869,15 +903,21 @@ class RestrictedEditingExceptionCommand extends Command {
     }
 }
 
-class StandardEditingModeEditing extends Plugin {
+/**
+ * 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.
+ */ class StandardEditingModeEditing extends Plugin {
     /**
-     * @inheritDoc
-     */ static get pluginName() {
+	 * @inheritDoc
+	 */ static get pluginName() {
         return 'StandardEditingModeEditing';
     }
     /**
-     * @inheritDoc
-     */ init() {
+	 * @inheritDoc
+	 */ init() {
         const editor = this.editor;
         editor.model.schema.extend('$text', {
             allowAttributes: [
@@ -915,15 +955,19 @@ class StandardEditingModeEditing extends Plugin {
 
 var unlockIcon = "<svg viewBox=\"0 0 20 20\" xmlns=\"http://www.w3.org/2000/svg\"><path d=\"M6.25 16a.75.75 0 1 1 0 1.5H.75a.75.75 0 1 1 0-1.5h5.5zm0-5a.75.75 0 1 1 0 1.5H.75a.75.75 0 1 1 0-1.5h5.5zm3-5a.75.75 0 0 1 0 1.5H.75a.75.75 0 0 1 0-1.5h8.5zm6-5a.75.75 0 1 1 0 1.5H.75a.75.75 0 0 1 0-1.5h14.5zm.25 5.5a3.5 3.5 0 0 1 3.143 1.959.75.75 0 0 1-1.36.636A2 2 0 0 0 13.5 10v2H19a1 1 0 0 1 1 1v5a1 1 0 0 1-1 1h-7a1 1 0 0 1-1-1v-5a1 1 0 0 1 1-1v-2l.005-.192A3.5 3.5 0 0 1 15.5 6.5zm0 7.5a.5.5 0 0 0-.492.41L15 14.5v2a.5.5 0 0 0 .992.09L16 16.5v-2a.5.5 0 0 0-.5-.5z\"/></svg>";
 
-class StandardEditingModeUI extends Plugin {
+/**
+ * The standard editing mode UI feature.
+ *
+ * It introduces the `'restrictedEditingException'` button that marks text as unrestricted for editing.
+ */ class StandardEditingModeUI extends Plugin {
     /**
-     * @inheritDoc
-     */ static get pluginName() {
+	 * @inheritDoc
+	 */ static get pluginName() {
         return 'StandardEditingModeUI';
     }
     /**
-     * @inheritDoc
-     */ init() {
+	 * @inheritDoc
+	 */ init() {
         const editor = this.editor;
         editor.ui.componentFactory.add('restrictedEditingException', ()=>{
             const button = this._createButton(ButtonView);
@@ -938,8 +982,8 @@ class StandardEditingModeUI extends Plugin {
         });
     }
     /**
-     * Creates a button for restricted editing exception command to use either in toolbar or in menu bar.
-     */ _createButton(ButtonClass) {
+	 * Creates a button for restricted editing exception command to use either in toolbar or in menu bar.
+	 */ _createButton(ButtonClass) {
         const editor = this.editor;
         const locale = editor.locale;
         const command = this.editor.commands.get('restrictedEditingException');
@@ -959,10 +1003,17 @@ class StandardEditingModeUI extends Plugin {
     }
 }
 
-class StandardEditingMode extends Plugin {
+/**
+ * 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}.
+ */ class StandardEditingMode extends Plugin {
     /**
-     * @inheritDoc
-     */ static get pluginName() {
+	 * @inheritDoc
+	 */ static get pluginName() {
         return 'StandardEditingMode';
     }
     static get requires() {