@ckeditor/ckeditor5-typing 36.0.1 → 37.0.0-alpha.0

package/src/inserttextobserver.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import { DomEventData, Observer, type View, type ViewDocumentSelection, type ViewRange, type ViewSelection } from '@ckeditor/ckeditor5-engine';
+/**
+ * Text insertion observer introduces the {@link module:engine/view/document~Document#event:insertText} event.
+ */
+export default class InsertTextObserver extends Observer {
+    /**
+     * @inheritDoc
+     */
+    constructor(view: View);
+    /**
+     * @inheritDoc
+     */
+    observe(): void;
+}
+/**
+ * Event fired when the user types text, for instance presses <kbd>A</kbd> or <kbd>?</kbd> in the
+ * editing view document.
+ *
+ * **Note**: This event will **not** fire for keystrokes such as <kbd>Delete</kbd> or <kbd>Enter</kbd>.
+ * They have dedicated events, see {@link module:engine/view/document~Document#event:delete} and
+ * {@link module:engine/view/document~Document#event:enter} to learn more.
+ *
+ * **Note**: This event is fired by the {@link module:typing/inserttextobserver~InsertTextObserver input feature}.
+ *
+ * @eventName module:engine/view/document~Document#event:insertText
+ * @param data The event data.
+ */
+export type ViewDocumentInsertTextEvent = {
+    name: 'insertText';
+    args: [data: InsertTextEventData];
+};
+export interface InsertTextEventData extends DomEventData {
+    /**
+     *  The text to be inserted.
+     */
+    text: string;
+    /**
+     * The selection into which the text should be inserted.
+     * If not specified, the insertion should occur at the current view selection.
+     */
+    selection: ViewSelection | ViewDocumentSelection;
+    /**
+     * The range that view selection should be set to after insertion.
+     */
+    resultRange?: ViewRange;
+}

package/src/inserttextobserver.js

@@ -21,8 +21,6 @@ const TYPING_INPUT_TYPES = [
 ];
 /**
  * Text insertion observer introduces the {@link module:engine/view/document~Document#event:insertText} event.
- *
- * @extends module:engine/view/observer/observer~Observer
  */
 export default class InsertTextObserver extends Observer {
     /**
@@ -68,7 +66,7 @@ export default class InsertTextObserver extends Observer {
             if (!data) {
                 return;
             }
-            // @if CK_DEBUG_TYPING // if ( window.logCKETyping ) {
+            // @if CK_DEBUG_TYPING // if ( ( window as any ).logCKETyping ) {
             // @if CK_DEBUG_TYPING // 	console.log( `%c[InsertTextObserver]%c Fire insertText event, text: ${ JSON.stringify( data ) }`,
             // @if CK_DEBUG_TYPING // 		'font-weight: bold; color: green;', ''
             // @if CK_DEBUG_TYPING // 	);

package/src/texttransformation.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module typing/texttransformation
+ */
+import { Plugin, type Editor, type PluginDependencies } from '@ckeditor/ckeditor5-core';
+/**
+ * The text transformation plugin.
+ */
+export default class TextTransformation extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'TextTransformation';
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Create new TextWatcher listening to the editor for typing and selection events.
+     */
+    private _enableTransformationWatchers;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [TextTransformation.pluginName]: TextTransformation;
+    }
+}

package/src/texttransformation.js

@@ -60,8 +60,6 @@ const DEFAULT_TRANSFORMATIONS = [
 ];
 /**
  * The text transformation plugin.
- *
- * @extends module:core/plugin~Plugin
  */
 export default class TextTransformation extends Plugin {
     /**
@@ -101,8 +99,6 @@ export default class TextTransformation extends Plugin {
     }
     /**
      * Create new TextWatcher listening to the editor for typing and selection events.
-     *
-     * @private
      */
     _enableTransformationWatchers() {
         const editor = this.editor;
@@ -150,12 +146,11 @@ export default class TextTransformation extends Plugin {
         watcher.bind('isEnabled').to(this);
     }
 }
-// Normalizes the configuration `from` parameter value.
-// The normalized value for the `from` parameter is a RegExp instance. If the passed `from` is already a RegExp instance,
-// it is returned unchanged.
-//
-// @param {String|RegExp} from
-// @returns {RegExp}
+/**
+ * Normalizes the configuration `from` parameter value.
+ * The normalized value for the `from` parameter is a RegExp instance. If the passed `from` is already a RegExp instance,
+ * it is returned unchanged.
+ */
 function normalizeFrom(from) {
     if (typeof from == 'string') {
         return new RegExp(`(${escapeRegExp(from)})$`);
@@ -163,12 +158,11 @@ function normalizeFrom(from) {
     // `from` is already a regular expression.
     return from;
 }
-// Normalizes the configuration `to` parameter value.
-// The normalized value for the `to` parameter is a function that takes an array and returns an array. See more in the
-// configuration description. If the passed `to` is already a function, it is returned unchanged.
-//
-// @param {String|Array.<null|String>|Function} to
-// @returns {Function}
+/**
+ * Normalizes the configuration `to` parameter value.
+ * The normalized value for the `to` parameter is a function that takes an array and returns an array. See more in the
+ * configuration description. If the passed `to` is already a function, it is returned unchanged.
+ */
 function normalizeTo(to) {
     if (typeof to == 'string') {
         return () => [to];
@@ -179,26 +173,25 @@ function normalizeTo(to) {
     // `to` is already a function.
     return to;
 }
-// For given `position` returns attributes for the text that is after that position.
-// The text can be in the same text node as the position (`foo[]bar`) or in the next text node (`foo[]<$text bold="true">bar</$text>`).
-//
-// @param {module:engine/model/position~Position} position
-// @returns {Iterable.<*>}
+/**
+ * For given `position` returns attributes for the text that is after that position.
+ * The text can be in the same text node as the position (`foo[]bar`) or in the next text node (`foo[]<$text bold="true">bar</$text>`).
+ */
 function getTextAttributesAfterPosition(position) {
     const textNode = position.textNode ? position.textNode : position.nodeAfter;
     return textNode.getAttributes();
 }
-// Returns a RegExp pattern string that detects a sentence inside a quote.
-//
-// @param {String} quoteCharacter The character to create a pattern for.
-// @returns {String}
+/**
+ * Returns a RegExp pattern string that detects a sentence inside a quote.
+ *
+ * @param quoteCharacter The character to create a pattern for.
+ */
 function buildQuotesRegExp(quoteCharacter) {
     return new RegExp(`(^|\\s)(${quoteCharacter})([^${quoteCharacter}]*)(${quoteCharacter})$`);
 }
-// Reads text transformation config and returns normalized array of transformations objects.
-//
-// @param {module:typing/texttransformation~TextTransformationDescription} config
-// @returns {Array.<{from:String,to:Function}>}
+/**
+ * Reads text transformation config and returns normalized array of transformations objects.
+ */
 function normalizeTransformations(config) {
     const extra = config.extra || [];
     const remove = config.remove || [];
@@ -214,11 +207,10 @@ function normalizeTransformations(config) {
         to: normalizeTo(transformation.to)
     }));
 }
-// Reads definitions and expands named groups if needed to transformation names.
-// This method also removes duplicated named transformations if any.
-//
-// @param {Array.<String|Object>} definitions
-// @returns {Array.<String|Object>}
+/**
+ * Reads definitions and expands named groups if needed to transformation names.
+ * This method also removes duplicated named transformations if any.
+ */
 function expandGroupsAndRemoveDuplicates(definitions) {
     // Set is using to make sure that transformation names are not duplicated.
     const definedTransformations = new Set();

package/src/textwatcher.d.ts

@@ -0,0 +1,138 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import type { Batch, Model, Range } from '@ckeditor/ckeditor5-engine';
+declare const TextWatcher_base: {
+    new (): import("@ckeditor/ckeditor5-utils").Observable;
+    prototype: import("@ckeditor/ckeditor5-utils").Observable;
+};
+/**
+ * The text watcher feature.
+ *
+ * Fires the {@link module:typing/textwatcher~TextWatcher#event:matched:data `matched:data`},
+ * {@link module:typing/textwatcher~TextWatcher#event:matched:selection `matched:selection`} and
+ * {@link module:typing/textwatcher~TextWatcher#event:unmatched `unmatched`} events on typing or selection changes.
+ */
+export default class TextWatcher extends TextWatcher_base {
+    /**
+     * The editor's model.
+     */
+    readonly model: Model;
+    /**
+     * The function used to match the text.
+     *
+     * The test callback can return 3 values:
+     *
+     * * `false` if there is no match,
+     * * `true` if there is a match,
+     * * an object if there is a match and we want to pass some additional information to the {@link #event:matched:data} event.
+     */
+    testCallback: (text: string) => unknown;
+    /**
+     * Whether there is a match currently.
+     */
+    private _hasMatch;
+    /**
+     * Flag indicating whether the `TextWatcher` instance is enabled or disabled.
+     * A disabled TextWatcher will not evaluate text.
+     *
+     * To disable TextWatcher:
+     *
+     * ```ts
+     * const watcher = new TextWatcher( editor.model, testCallback );
+     *
+     * // After this a testCallback will not be called.
+     * watcher.isEnabled = false;
+     * ```
+     */
+    isEnabled: boolean;
+    /**
+     * Creates a text watcher instance.
+     *
+     * @param testCallback See {@link module:typing/textwatcher~TextWatcher#testCallback}.
+     */
+    constructor(model: Model, testCallback: (text: string) => unknown);
+    /**
+     * Flag indicating whether there is a match currently.
+     */
+    get hasMatch(): boolean;
+    /**
+     * Starts listening to the editor for typing and selection events.
+     */
+    private _startListening;
+    /**
+     * Checks the editor content for matched text.
+     *
+     * @fires matched:data
+     * @fires matched:selection
+     * @fires unmatched
+     *
+     * @param suffix A suffix used for generating the event name.
+     * @param data Data object for event.
+     */
+    private _evaluateTextBeforeSelection;
+}
+export type TextWatcherMatchedEvent<TCallbackResult extends Record<string, unknown> = Record<string, unknown>> = {
+    name: 'matched' | 'matched:data' | 'matched:selection';
+    args: [
+        {
+            text: string;
+            range: Range;
+            batch?: Batch;
+        } & TCallbackResult
+    ];
+};
+/**
+ * Fired whenever the text watcher found a match for data changes.
+ *
+ * @eventName matched:data
+ * @param data Event data.
+ * @param data.testResult The additional data returned from the {@link module:typing/textwatcher~TextWatcher#testCallback}.
+ */
+export type TextWatcherMatchedDataEvent<TCallbackResult extends Record<string, unknown>> = {
+    name: 'matched:data';
+    args: [data: TextWatcherMatchedDataEventData & TCallbackResult];
+};
+export interface TextWatcherMatchedDataEventData {
+    /**
+     * The full text before selection to which the regexp was applied.
+     */
+    text: string;
+    /**
+     * The range representing the position of the `data.text`.
+     */
+    range: Range;
+    batch: Batch;
+}
+/**
+ * Fired whenever the text watcher found a match for selection changes.
+ *
+ * @eventName matched:selection
+ * @param data Event data.
+ * @param data.testResult The additional data returned from the {@link module:typing/textwatcher~TextWatcher#testCallback}.
+ */
+export type TextWatcherMatchedSelectionEvent<TCallbackResult extends Record<string, unknown>> = {
+    name: 'matched:selection';
+    args: [data: TextWatcherMatchedSelectionEventData & TCallbackResult];
+};
+export interface TextWatcherMatchedSelectionEventData {
+    /**
+     * The full text before selection.
+     */
+    text: string;
+    /**
+     * The range representing the position of the `data.text`.
+     */
+    range: Range;
+}
+/**
+ * Fired whenever the text does not match anymore. Fired only when the text watcher found a match.
+ *
+ * @eventName unmatched
+ */
+export type TextWatcherUnmatchedEvent = {
+    name: 'unmatched';
+    args: [];
+};
+export {};

package/src/textwatcher.js

@@ -13,60 +13,18 @@ import getLastTextLine from './utils/getlasttextline';
  * Fires the {@link module:typing/textwatcher~TextWatcher#event:matched:data `matched:data`},
  * {@link module:typing/textwatcher~TextWatcher#event:matched:selection `matched:selection`} and
  * {@link module:typing/textwatcher~TextWatcher#event:unmatched `unmatched`} events on typing or selection changes.
- *
- * @private
- * @mixes module:utils/observablemixin~ObservableMixin
  */
 export default class TextWatcher extends ObservableMixin() {
     /**
      * Creates a text watcher instance.
      *
-     * @param {module:engine/model/model~Model} model
-     * @param {Function} testCallback See {@link module:typing/textwatcher~TextWatcher#testCallback}.
+     * @param testCallback See {@link module:typing/textwatcher~TextWatcher#testCallback}.
      */
     constructor(model, testCallback) {
         super();
-        /**
-         * The editor's model.
-         *
-         * @readonly
-         * @member {module:engine/model/model~Model}
-         */
         this.model = model;
-        /**
-         * The function used to match the text.
-         *
-         * The test callback can return 3 values:
-         *
-         * * `false` if there is no match,
-         * * `true` if there is a match,
-         * * an object if there is a match and we want to pass some additional information to the {@link #event:matched:data} event.
-         *
-         * @member {Function} #testCallback
-         * @returns {Object} testResult
-         */
         this.testCallback = testCallback;
-        /**
-         * Whether there is a match currently.
-         *
-         * @readonly
-         * @member {Boolean}
-         */
         this._hasMatch = false;
-        /**
-         * Flag indicating whether the `TextWatcher` instance is enabled or disabled.
-         * A disabled TextWatcher will not evaluate text.
-         *
-         * To disable TextWatcher:
-         *
-         *		const watcher = new TextWatcher( editor.model, testCallback );
-         *
-         *		// After this a testCallback will not be called.
-         *		watcher.isEnabled = false;
-         *
-         * @observable
-         * @member {Boolean} #isEnabled
-         */
         this.set('isEnabled', true);
         // Toggle text watching on isEnabled state change.
         this.on('change:isEnabled', () => {
@@ -81,15 +39,13 @@ export default class TextWatcher extends ObservableMixin() {
         this._startListening();
     }
     /**
-     * TODO
+     * Flag indicating whether there is a match currently.
      */
     get hasMatch() {
         return this._hasMatch;
     }
     /**
      * Starts listening to the editor for typing and selection events.
-     *
-     * @private
      */
     _startListening() {
         const model = this.model;
@@ -123,9 +79,8 @@ export default class TextWatcher extends ObservableMixin() {
      * @fires matched:selection
      * @fires unmatched
      *
-     * @private
-     * @param {'data'|'selection'} suffix A suffix used for generating the event name.
-     * @param {Object} data Data object for event.
+     * @param suffix A suffix used for generating the event name.
+     * @param data Data object for event.
      */
     _evaluateTextBeforeSelection(suffix, data = {}) {
         const model = this.model;
@@ -148,8 +103,3 @@ export default class TextWatcher extends ObservableMixin() {
         }
     }
 }
-/**
- * Fired whenever the text does not match anymore. Fired only when the text watcher found a match.
- *
- * @event unmatched
- */

package/src/twostepcaretmovement.d.ts

@@ -0,0 +1,204 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module typing/twostepcaretmovement
+ */
+import { Plugin, type Editor } from '@ckeditor/ckeditor5-core';
+/**
+ * This plugin enables the two-step caret (phantom) movement behavior for
+ * {@link module:typing/twostepcaretmovement~TwoStepCaretMovement#registerAttribute registered attributes}
+ * on arrow right (<kbd>→</kbd>) and left (<kbd>←</kbd>) key press.
+ *
+ * Thanks to this (phantom) caret movement the user is able to type before/after as well as at the
+ * beginning/end of an attribute.
+ *
+ * **Note:** This plugin support right–to–left (Arabic, Hebrew, etc.) content by mirroring its behavior
+ * but for the sake of simplicity examples showcase only left–to–right use–cases.
+ *
+ * # Forward movement
+ *
+ * ## "Entering" an attribute:
+ *
+ * When this plugin is enabled and registered for the `a` attribute and the selection is right before it
+ * (at the attribute boundary), pressing the right arrow key will not move the selection but update its
+ * attributes accordingly:
+ *
+ * * When enabled:
+ *
+ * ```xml
+ * foo{}<$text a="true">bar</$text>
+ * ```
+ *
+ * 	<kbd>→</kbd>
+ *
+ * ```xml
+ * foo<$text a="true">{}bar</$text>
+ * ```
+ *
+ * * When disabled:
+ *
+ * ```xml
+ * foo{}<$text a="true">bar</$text>
+ * ```
+ *
+ * 	<kbd>→</kbd>
+ *
+ * ```xml
+ * foo<$text a="true">b{}ar</$text>
+ * ```
+ *
+ *
+ * ## "Leaving" an attribute:
+ *
+ * * When enabled:
+ *
+ * ```xml
+ * <$text a="true">bar{}</$text>baz
+ * ```
+ *
+ * 	<kbd>→</kbd>
+ *
+ * ```xml
+ * <$text a="true">bar</$text>{}baz
+ * ```
+ *
+ * * When disabled:
+ *
+ * ```xml
+ * <$text a="true">bar{}</$text>baz
+ * ```
+ *
+ * 	<kbd>→</kbd>
+ *
+ * ```xml
+ * <$text a="true">bar</$text>b{}az
+ * ```
+ *
+ * # Backward movement
+ *
+ * * When enabled:
+ *
+ * ```xml
+ * <$text a="true">bar</$text>{}baz
+ * ```
+ *
+ * 	<kbd>←</kbd>
+ *
+ * ```xml
+ * <$text a="true">bar{}</$text>baz
+ * ```
+ *
+ * * When disabled:
+ *
+ * ```xml
+ * <$text a="true">bar</$text>{}baz
+ * ```
+ *
+ * 	<kbd>←</kbd>
+ *
+ * ```xml
+ * <$text a="true">ba{}r</$text>b{}az
+ * ```
+ *
+ * # Multiple attributes
+ *
+ * * When enabled and many attributes starts or ends at the same position:
+ *
+ * ```xml
+ * <$text a="true" b="true">bar</$text>{}baz
+ * ```
+ *
+ * 	<kbd>←</kbd>
+ *
+ * ```xml
+ * <$text a="true" b="true">bar{}</$text>baz
+ * ```
+ *
+ * * When enabled and one procedes another:
+ *
+ * ```xml
+ * <$text a="true">bar</$text><$text b="true">{}bar</$text>
+ * ```
+ *
+ * 	<kbd>←</kbd>
+ *
+ * ```xml
+ * <$text a="true">bar{}</$text><$text b="true">bar</$text>
+ * ```
+ *
+ */
+export default class TwoStepCaretMovement extends Plugin {
+    /**
+     * A set of attributes to handle.
+     */
+    private attributes;
+    /**
+     * The current UID of the overridden gravity, as returned by
+     * {@link module:engine/model/writer~Writer#overrideSelectionGravity}.
+     */
+    private _overrideUid;
+    /**
+     * A flag indicating that the automatic gravity restoration should not happen upon the next
+     * gravity restoration.
+     * {@link module:engine/model/selection~Selection#event:change:range} event.
+     */
+    private _isNextGravityRestorationSkipped;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'TwoStepCaretMovement';
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Registers a given attribute for the two-step caret movement.
+     *
+     * @param attribute Name of the attribute to handle.
+     */
+    registerAttribute(attribute: string): void;
+    /**
+     * Updates the document selection and the view according to the two–step caret movement state
+     * when moving **forwards**. Executed upon `keypress` in the {@link module:engine/view/view~View}.
+     *
+     * @param data Data of the key press.
+     * @returns `true` when the handler prevented caret movement.
+     */
+    private _handleForwardMovement;
+    /**
+     * Updates the document selection and the view according to the two–step caret movement state
+     * when moving **backwards**. Executed upon `keypress` in the {@link module:engine/view/view~View}.
+     *
+     * @param data Data of the key press.
+     * @returns `true` when the handler prevented caret movement
+     */
+    private _handleBackwardMovement;
+    /**
+     * `true` when the gravity is overridden for the plugin.
+     */
+    private get _isGravityOverridden();
+    /**
+     * Overrides the gravity using the {@link module:engine/model/writer~Writer model writer}
+     * and stores the information about this fact in the {@link #_overrideUid}.
+     *
+     * A shorthand for {@link module:engine/model/writer~Writer#overrideSelectionGravity}.
+     */
+    private _overrideGravity;
+    /**
+     * Restores the gravity using the {@link module:engine/model/writer~Writer model writer}.
+     *
+     * A shorthand for {@link module:engine/model/writer~Writer#restoreSelectionGravity}.
+     */
+    private _restoreGravity;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [TwoStepCaretMovement.pluginName]: TwoStepCaretMovement;
+    }
+}