@ckeditor/ckeditor5-autoformat 36.0.0 → 37.0.0-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-autoformat",
-  "version": "36.0.0",
+  "version": "37.0.0-alpha.0",
   "description": "Autoformatting feature for CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -12,24 +12,24 @@
   ],
   "main": "src/index.js",
   "dependencies": {
-    "ckeditor5": "^36.0.0"
+    "ckeditor5": "^37.0.0-alpha.0"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-basic-styles": "^36.0.0",
-    "@ckeditor/ckeditor5-block-quote": "^36.0.0",
-    "@ckeditor/ckeditor5-code-block": "^36.0.0",
-    "@ckeditor/ckeditor5-core": "^36.0.0",
-    "@ckeditor/ckeditor5-dev-utils": "^32.0.0",
-    "@ckeditor/ckeditor5-editor-classic": "^36.0.0",
-    "@ckeditor/ckeditor5-engine": "^36.0.0",
-    "@ckeditor/ckeditor5-enter": "^36.0.0",
-    "@ckeditor/ckeditor5-heading": "^36.0.0",
-    "@ckeditor/ckeditor5-horizontal-line": "^36.0.0",
-    "@ckeditor/ckeditor5-list": "^36.0.0",
-    "@ckeditor/ckeditor5-paragraph": "^36.0.0",
-    "@ckeditor/ckeditor5-theme-lark": "^36.0.0",
-    "@ckeditor/ckeditor5-typing": "^36.0.0",
-    "@ckeditor/ckeditor5-undo": "^36.0.0",
+    "@ckeditor/ckeditor5-basic-styles": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-block-quote": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-code-block": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-core": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-dev-utils": "^34.0.0",
+    "@ckeditor/ckeditor5-editor-classic": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-engine": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-enter": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-heading": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-horizontal-line": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-list": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-paragraph": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-theme-lark": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-typing": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-undo": "^37.0.0-alpha.0",
     "typescript": "^4.8.4",
     "webpack": "^5.58.1",
     "webpack-cli": "^4.9.0"
@@ -63,5 +63,6 @@
     "dll:build": "webpack",
     "build": "tsc -p ./tsconfig.release.json",
     "postversion": "npm run build"
-  }
+  },
+  "types": "src/index.d.ts"
 }

package/src/autoformat.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @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 { Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+/**
+ * Enables a set of predefined autoformatting actions.
+ *
+ * For a detailed overview, check the {@glink features/autoformat Autoformatting} feature guide
+ * and the {@glink api/autoformat package page}.
+ */
+export default class Autoformat extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'Autoformat';
+    /**
+     * @inheritDoc
+     */
+    afterInit(): void;
+    /**
+     * Adds autoformatting related to the {@link module:list/list~List}.
+     *
+     * When typed:
+     * - `* ` or `- ` – A paragraph will be changed into a bulleted list.
+     * - `1. ` or `1) ` – A paragraph will be changed into a numbered list ("1" can be any digit or a list of digits).
+     * - `[] ` or `[ ] ` – A paragraph will be changed into a to-do list.
+     * - `[x] ` or `[ x ] ` – A paragraph will be changed into a checked to-do list.
+     */
+    private _addListAutoformats;
+    /**
+     * Adds autoformatting related to the {@link module:basic-styles/bold~Bold},
+     * {@link module:basic-styles/italic~Italic}, {@link module:basic-styles/code~Code}
+     * and {@link module:basic-styles/strikethrough~Strikethrough}
+     *
+     * When typed:
+     * - `**foobar**` – `**` characters are removed and `foobar` is set to bold,
+     * - `__foobar__` – `__` characters are removed and `foobar` is set to bold,
+     * - `*foobar*` – `*` characters are removed and `foobar` is set to italic,
+     * - `_foobar_` – `_` characters are removed and `foobar` is set to italic,
+     * - ``` `foobar` – ``` ` ``` characters are removed and `foobar` is set to code,
+     * - `~~foobar~~` – `~~` characters are removed and `foobar` is set to strikethrough.
+     */
+    private _addBasicStylesAutoformats;
+    /**
+     * Adds autoformatting related to {@link module:heading/heading~Heading}.
+     *
+     * It is using a number at the end of the command name to associate it with the proper trigger:
+     *
+     * * `heading` with a `heading1` value will be executed when typing `#`,
+     * * `heading` with a `heading2` value will be executed when typing `##`,
+     * * ... up to `heading6` for `######`.
+     */
+    private _addHeadingAutoformats;
+    /**
+     * Adds autoformatting related to {@link module:block-quote/blockquote~BlockQuote}.
+     *
+     * When typed:
+     * * `> ` – A paragraph will be changed to a block quote.
+     */
+    private _addBlockQuoteAutoformats;
+    /**
+     * Adds autoformatting related to {@link module:code-block/codeblock~CodeBlock}.
+     *
+     * When typed:
+     * - `` ``` `` – A paragraph will be changed to a code block.
+     */
+    private _addCodeBlockAutoformats;
+    /**
+     * Adds autoformatting related to {@link module:horizontal-line/horizontalline~HorizontalLine}.
+     *
+     * When typed:
+     * - `` --- `` – Will be replaced with a horizontal line.
+     */
+    private _addHorizontalLineAutoformats;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [Autoformat.pluginName]: Autoformat;
+    }
+}

package/src/autoformat.js

@@ -9,12 +9,12 @@ import inlineAutoformatEditing from './inlineautoformatediting';
 /**
  * Enables a set of predefined autoformatting actions.
  *
- * For a detailed overview, check the {@glink features/autoformat Autoformatting feature documentation}
+ * For a detailed overview, check the {@glink features/autoformat Autoformatting} feature guide
  * and the {@glink api/autoformat package page}.
  */
 export default class Autoformat extends Plugin {
     /**
-     * @inheritdoc
+     * @inheritDoc
      */
     static get requires() {
         return [Delete];
@@ -40,10 +40,10 @@ export default class Autoformat extends Plugin {
      * Adds autoformatting related to the {@link module:list/list~List}.
      *
      * When typed:
-     * - `* ` or `- ` – A paragraph will be changed to a bulleted list.
-     * - `1. ` or `1) ` – A paragraph will be changed to a numbered list ("1" can be any digit or a list of digits).
-     * - `[] ` or `[ ] ` – A paragraph will be changed to a to-do list.
-     * - `[x] ` or `[ x ] ` – A paragraph will be changed to a checked to-do list.
+     * - `* ` or `- ` – A paragraph will be changed into a bulleted list.
+     * - `1. ` or `1) ` – A paragraph will be changed into a numbered list ("1" can be any digit or a list of digits).
+     * - `[] ` or `[ ] ` – A paragraph will be changed into a to-do list.
+     * - `[x] ` or `[ x ] ` – A paragraph will be changed into a checked to-do list.
      */
     _addListAutoformats() {
         const commands = this.editor.commands;
@@ -104,9 +104,9 @@ export default class Autoformat extends Plugin {
      *
      * It is using a number at the end of the command name to associate it with the proper trigger:
      *
-     * * `heading` with value `heading1` will be executed when typing `#`,
-     * * `heading` with value `heading2` will be executed when typing `##`,
-     * * ... up to `heading6` and `######`.
+     * * `heading` with a `heading1` value will be executed when typing `#`,
+     * * `heading` with a `heading2` value will be executed when typing `##`,
+     * * ... up to `heading6` for `######`.
      */
     _addHeadingAutoformats() {
         const command = this.editor.commands.get('heading');

package/src/blockautoformatediting.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @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 { Editor } from 'ckeditor5/src/core';
+import type Autoformat from './autoformat';
+/**
+ * The block autoformatting engine. It allows to format various block patterns. For example,
+ * it can be configured to turn a paragraph starting with `*` and followed by a space into a list item.
+ *
+ * The autoformatting operation is integrated with the undo manager,
+ * so the autoformatting step can be undone if the user's intention was not to format the text.
+ *
+ * See the {@link module:autoformat/blockautoformatediting~blockAutoformatEditing `blockAutoformatEditing`} documentation
+ * to learn how to create custom block autoformatters. You can also use
+ * the {@link module:autoformat/autoformat~Autoformat} feature which enables a set of default autoformatters
+ * (lists, headings, bold and italic).
+ *
+ * @module autoformat/blockautoformatediting
+ */
+/**
+ * Creates a listener triggered on {@link module:engine/model/document~Document#event:change:data `change:data`} event in the document.
+ * Calls the callback when inserted text matches the regular expression or the command name
+ * if provided instead of the callback.
+ *
+ * Examples of usage:
+ *
+ * To convert a paragraph into heading 1 when `- ` is typed, using just the command name:
+ *
+ * ```ts
+ * blockAutoformatEditing( editor, plugin, /^\- $/, 'heading1' );
+ * ```
+ *
+ * To convert a paragraph into heading 1 when `- ` is typed, using just the callback:
+ *
+ * ```ts
+ * blockAutoformatEditing( editor, plugin, /^\- $/, ( context ) => {
+ * 	const { match } = context;
+ * 	const headingLevel = match[ 1 ].length;
+ *
+ * 	editor.execute( 'heading', {
+ * 		formatId: `heading${ headingLevel }`
+ * 	} );
+ * } );
+ * ```
+ *
+ * @param editor The editor instance.
+ * @param plugin The autoformat plugin instance.
+ * @param pattern The regular expression to execute on just inserted text. The regular expression is tested against the text
+ * from the beginning until the caret position.
+ * @param callbackOrCommand The callback to execute or the command to run when the text is matched.
+ * In case of providing the callback, it receives the following parameter:
+ * * match RegExp.exec() result of matching the pattern to inserted text.
+ */
+export default function blockAutoformatEditing(editor: Editor, plugin: Autoformat, pattern: RegExp, callbackOrCommand: string | ((context: {
+    match: RegExpExecArray;
+}) => unknown)): void;

package/src/blockautoformatediting.js

@@ -25,13 +25,13 @@ import { first } from 'ckeditor5/src/utils';
  *
  * Examples of usage:
  *
- * To convert a paragraph to heading 1 when `- ` is typed, using just the command name:
+ * To convert a paragraph into heading 1 when `- ` is typed, using just the command name:
  *
  * ```ts
  * blockAutoformatEditing( editor, plugin, /^\- $/, 'heading1' );
  * ```
  *
- * To convert a paragraph to heading 1 when `- ` is typed, using just the callback:
+ * To convert a paragraph into heading 1 when `- ` is typed, using just the callback:
  *
  * ```ts
  * blockAutoformatEditing( editor, plugin, /^\- $/, ( context ) => {
@@ -50,7 +50,7 @@ import { first } from 'ckeditor5/src/utils';
  * from the beginning until the caret position.
  * @param callbackOrCommand The callback to execute or the command to run when the text is matched.
  * In case of providing the callback, it receives the following parameter:
- * * {Object} match RegExp.exec() result of matching the pattern to inserted text.
+ * * match RegExp.exec() result of matching the pattern to inserted text.
  */
 export default function blockAutoformatEditing(editor, plugin, pattern, callbackOrCommand) {
     let callback;
@@ -93,8 +93,8 @@ export default function blockAutoformatEditing(editor, plugin, pattern, callback
             !['numberedList', 'bulletedList', 'todoList'].includes(callbackOrCommand)) {
             return;
         }
-        // In case a command is bound, do not re-execute it over an existing block style which would result with a style removal.
-        // Instead just drop processing so that autoformat trigger text is not lost. E.g. writing "# " in a level 1 heading.
+        // In case a command is bound, do not re-execute it over an existing block style which would result in a style removal.
+        // Instead, just drop processing so that autoformat trigger text is not lost. E.g. writing "# " in a level 1 heading.
         if (command && command.value === true) {
             return;
         }
@@ -129,7 +129,8 @@ export default function blockAutoformatEditing(editor, plugin, pattern, callback
             }
             range.detach();
             editor.model.enqueueChange(() => {
-                editor.plugins.get('Delete').requestUndoOnBackspace();
+                const deletePlugin = editor.plugins.get('Delete');
+                deletePlugin.requestUndoOnBackspace();
             });
         });
     });

package/src/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @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 autoformat
+ */
+export { default as Autoformat } from './autoformat';

package/src/inlineautoformatediting.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @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
+ */
+/**
+ * The inline autoformatting engine. It allows to format various inline patterns. For example,
+ * it can be configured to make "foo" bold when typed `**foo**` (the `**` markers will be removed).
+ *
+ * The autoformatting operation is integrated with the undo manager,
+ * so the autoformatting step can be undone if the user's intention was not to format the text.
+ *
+ * See the {@link module:autoformat/inlineautoformatediting~inlineAutoformatEditing `inlineAutoformatEditing`} documentation
+ * to learn how to create custom inline autoformatters. You can also use
+ * the {@link module:autoformat/autoformat~Autoformat} feature which enables a set of default autoformatters
+ * (lists, headings, bold and italic).
+ *
+ * @module autoformat/inlineautoformatediting
+ */
+import type { Editor } from 'ckeditor5/src/core';
+import type { Range, Writer } from 'ckeditor5/src/engine';
+import type Autoformat from './autoformat';
+export type TestCallback = (text: string) => {
+    remove: Array<Array<number>>;
+    format: Array<Array<number>>;
+};
+/**
+ * Enables autoformatting mechanism for a given {@link module:core/editor/editor~Editor}.
+ *
+ * It formats the matched text by applying the given model attribute or by running the provided formatting callback.
+ * On every {@link module:engine/model/document~Document#event:change:data data change} in the model document
+ * the autoformatting engine checks the text on the left of the selection
+ * and executes the provided action if the text matches given criteria (regular expression or callback).
+ *
+ * @param editor The editor instance.
+ * @param plugin The autoformat plugin instance.
+ * @param testRegexpOrCallback The regular expression or callback to execute on text.
+ * Provided regular expression *must* have three capture groups. The first and the third capture group
+ * should match opening and closing delimiters. The second capture group should match the text to format.
+ *
+ * ```ts
+ * // Matches the `**bold text**` pattern.
+ * // There are three capturing groups:
+ * // - The first to match the starting `**` delimiter.
+ * // - The second to match the text to format.
+ * // - The third to match the ending `**` delimiter.
+ * inlineAutoformatEditing( editor, plugin, /(\*\*)([^\*]+?)(\*\*)$/g, formatCallback );
+ * ```
+ *
+ * When a function is provided instead of the regular expression, it will be executed with the text to match as a parameter.
+ * The function should return proper "ranges" to delete and format.
+ *
+ * ```ts
+ * {
+ * 	remove: [
+ * 		[ 0, 1 ],	// Remove the first letter from the given text.
+ * 		[ 5, 6 ]	// Remove the 6th letter from the given text.
+ * 	],
+ * 	format: [
+ * 		[ 1, 5 ]	// Format all letters from 2nd to 5th.
+ * 	]
+ * }
+ * ```
+ *
+ * @param formatCallback A callback to apply actual formatting.
+ * It should return `false` if changes should not be applied (e.g. if a command is disabled).
+ *
+ * ```ts
+ * inlineAutoformatEditing( editor, plugin, /(\*\*)([^\*]+?)(\*\*)$/g, ( writer, rangesToFormat ) => {
+ * 	const command = editor.commands.get( 'bold' );
+ *
+ * 	if ( !command.isEnabled ) {
+ * 		return false;
+ * 	}
+ *
+ * 	const validRanges = editor.model.schema.getValidRanges( rangesToFormat, 'bold' );
+ *
+ * 	for ( let range of validRanges ) {
+ * 		writer.setAttribute( 'bold', true, range );
+ * 	}
+ * } );
+ * ```
+ */
+export default function inlineAutoformatEditing(editor: Editor, plugin: Autoformat, testRegexpOrCallback: RegExp | TestCallback, formatCallback: (writer: Writer, rangesToFormat: Array<Range>) => boolean | undefined): void;

package/src/inlineautoformatediting.js

@@ -138,7 +138,8 @@ export default function inlineAutoformatEditing(editor, plugin, testRegexpOrCall
                 writer.remove(range);
             }
             model.enqueueChange(() => {
-                editor.plugins.get('Delete').requestUndoOnBackspace();
+                const deletePlugin = editor.plugins.get('Delete');
+                deletePlugin.requestUndoOnBackspace();
             });
         });
     });