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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-paragraph",
-  "version": "36.0.1",
+  "version": "37.0.0-alpha.0",
   "description": "Paragraph feature for CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -12,20 +12,20 @@
   ],
   "main": "src/index.js",
   "dependencies": {
-    "@ckeditor/ckeditor5-core": "^36.0.1",
-    "@ckeditor/ckeditor5-ui": "^36.0.1",
-    "@ckeditor/ckeditor5-utils": "^36.0.1"
+    "@ckeditor/ckeditor5-core": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-ui": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-utils": "^37.0.0-alpha.0"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-basic-styles": "^36.0.1",
-    "@ckeditor/ckeditor5-clipboard": "^36.0.1",
-    "@ckeditor/ckeditor5-editor-classic": "^36.0.1",
-    "@ckeditor/ckeditor5-engine": "^36.0.1",
-    "@ckeditor/ckeditor5-enter": "^36.0.1",
-    "@ckeditor/ckeditor5-heading": "^36.0.1",
-    "@ckeditor/ckeditor5-link": "^36.0.1",
-    "@ckeditor/ckeditor5-typing": "^36.0.1",
-    "@ckeditor/ckeditor5-undo": "^36.0.1",
+    "@ckeditor/ckeditor5-basic-styles": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-clipboard": "^37.0.0-alpha.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-link": "^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"
@@ -54,5 +54,6 @@
   "scripts": {
     "build": "tsc -p ./tsconfig.release.json",
     "postversion": "npm run build"
-  }
+  },
+  "types": "src/index.d.ts"
 }

package/src/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @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 paragraph
+ */
+export { default as Paragraph } from './paragraph';
+export { default as ParagraphButtonUI } from './paragraphbuttonui';
+export type { default as ParagraphCommand } from './paragraphcommand';

package/src/insertparagraphcommand.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @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 paragraph/insertparagraphcommand
+ */
+import { Command } from '@ckeditor/ckeditor5-core';
+import type { Position } from '@ckeditor/ckeditor5-engine';
+/**
+ * The insert paragraph command. It inserts a new paragraph at a specific
+ * {@link module:engine/model/position~Position document position}.
+ *
+ * ```ts
+ * // Insert a new paragraph before an element in the document.
+ * editor.execute( 'insertParagraph', {
+ *   position: editor.model.createPositionBefore( element )
+ * } );
+ * ```
+ *
+ * If a paragraph is disallowed in the context of the specific position, the command
+ * will attempt to split position ancestors to find a place where it is possible
+ * to insert a paragraph.
+ *
+ * **Note**: This command moves the selection to the inserted paragraph.
+ */
+export default class InsertParagraphCommand extends Command {
+    /**
+     * Executes the command.
+     *
+     * @param options Options for the executed command.
+     * @param options.position The model position at which the new paragraph will be inserted.
+     * @param options.attributes Attributes keys and values to set on a inserted paragraph.
+     * @fires execute
+     */
+    execute(options: {
+        position: Position;
+        attributes: Record<string, unknown>;
+    }): void;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface CommandsMap {
+        insertParagraph: InsertParagraphCommand;
+    }
+}

package/src/insertparagraphcommand.js

@@ -10,27 +10,26 @@ import { Command } from '@ckeditor/ckeditor5-core';
  * The insert paragraph command. It inserts a new paragraph at a specific
  * {@link module:engine/model/position~Position document position}.
  *
- *		// Insert a new paragraph before an element in the document.
- *		editor.execute( 'insertParagraph', {
- *			position: editor.model.createPositionBefore( element )
- *		} );
+ * ```ts
+ * // Insert a new paragraph before an element in the document.
+ * editor.execute( 'insertParagraph', {
+ *   position: editor.model.createPositionBefore( element )
+ * } );
+ * ```
  *
  * If a paragraph is disallowed in the context of the specific position, the command
  * will attempt to split position ancestors to find a place where it is possible
  * to insert a paragraph.
  *
  * **Note**: This command moves the selection to the inserted paragraph.
- *
- * @extends module:core/command~Command
  */
 export default class InsertParagraphCommand extends Command {
     /**
      * Executes the command.
      *
-     * @param {Object} options Options for the executed command.
-     * @param {module:engine/model/position~Position} options.position The model position at which
-     * the new paragraph will be inserted.
-     * @param {Object} attributes Attributes keys and values to set on a inserted paragraph
+     * @param options Options for the executed command.
+     * @param options.position The model position at which the new paragraph will be inserted.
+     * @param options.attributes Attributes keys and values to set on a inserted paragraph.
      * @fires execute
      */
     execute(options) {

package/src/paragraph.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @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 } from '@ckeditor/ckeditor5-core';
+/**
+ * The paragraph feature for the editor.
+ *
+ * It introduces the `<paragraph>` element in the model which renders as a `<p>` element in the DOM and data.
+ *
+ * It also brings two editors commands:
+ *
+ * * The {@link module:paragraph/paragraphcommand~ParagraphCommand `'paragraph'`} command that converts all
+ * blocks in the model selection into paragraphs.
+ * * The {@link module:paragraph/insertparagraphcommand~InsertParagraphCommand `'insertParagraph'`} command
+ * that inserts a new paragraph at a specified location in the model.
+ */
+export default class Paragraph extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'Paragraph';
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * A list of element names which should be treated by the autoparagraphing algorithms as
+     * paragraph-like. This means that e.g. the following content:
+     *
+     * ```html
+     * <h1>Foo</h1>
+     * <table>
+     *   <tr>
+     *     <td>X</td>
+     *     <td>
+     *       <ul>
+     *         <li>Y</li>
+     *         <li>Z</li>
+     *       </ul>
+     *     </td>
+     *   </tr>
+     * </table>
+     * ```
+     *
+     * contains five paragraph-like elements: `<h1>`, two `<td>`s and two `<li>`s.
+     * Hence, if none of the features is going to convert those elements the above content will be automatically handled
+     * by the paragraph feature and converted to:
+     *
+     * ```html
+     * <p>Foo</p>
+     * <p>X</p>
+     * <p>Y</p>
+     * <p>Z</p>
+     * ```
+     *
+     * Note: The `<td>` containing two `<li>` elements was ignored as the innermost paragraph-like elements
+     * have a priority upon conversion.
+     */
+    static paragraphLikeElements: Set<string>;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [Paragraph.pluginName]: Paragraph;
+    }
+}

package/src/paragraph.js

@@ -19,8 +19,6 @@ import { Plugin } from '@ckeditor/ckeditor5-core';
  * blocks in the model selection into paragraphs.
  * * The {@link module:paragraph/insertparagraphcommand~InsertParagraphCommand `'insertParagraph'`} command
  * that inserts a new paragraph at a specified location in the model.
- *
- * @extends module:core/plugin~Plugin
  */
 export default class Paragraph extends Plugin {
     /**
@@ -61,33 +59,35 @@ export default class Paragraph extends Plugin {
  * A list of element names which should be treated by the autoparagraphing algorithms as
  * paragraph-like. This means that e.g. the following content:
  *
- *		<h1>Foo</h1>
-*		<table>
-*			<tr>
-*				<td>X</td>
-*				<td>
-*					<ul>
-*						<li>Y</li>
-*						<li>Z</li>
-*					</ul>
-*				</td>
-*			</tr>
-*		</table>
-*
-* contains five paragraph-like elements: `<h1>`, two `<td>`s and two `<li>`s.
-* Hence, if none of the features is going to convert those elements the above content will be automatically handled
-* by the paragraph feature and converted to:
-*
-*		<p>Foo</p>
-*		<p>X</p>
-*		<p>Y</p>
-*		<p>Z</p>
-*
-* Note: The `<td>` containing two `<li>` elements was ignored as the innermost paragraph-like elements
-* have a priority upon conversion.
-*
-* @member {Set.<String>} module:paragraph/paragraph~Paragraph.paragraphLikeElements
-*/
+ * ```html
+ * <h1>Foo</h1>
+ * <table>
+ *   <tr>
+ *     <td>X</td>
+ *     <td>
+ *       <ul>
+ *         <li>Y</li>
+ *         <li>Z</li>
+ *       </ul>
+ *     </td>
+ *   </tr>
+ * </table>
+ * ```
+ *
+ * contains five paragraph-like elements: `<h1>`, two `<td>`s and two `<li>`s.
+ * Hence, if none of the features is going to convert those elements the above content will be automatically handled
+ * by the paragraph feature and converted to:
+ *
+ * ```html
+ * <p>Foo</p>
+ * <p>X</p>
+ * <p>Y</p>
+ * <p>Z</p>
+ * ```
+ *
+ * Note: The `<td>` containing two `<li>` elements was ignored as the innermost paragraph-like elements
+ * have a priority upon conversion.
+ */
 Paragraph.paragraphLikeElements = new Set([
     'blockquote',
     'dd',

package/src/paragraphbuttonui.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @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 paragraph/paragraphbuttonui
+ */
+import { Plugin, type PluginDependencies } from '@ckeditor/ckeditor5-core';
+/**
+ * This plugin defines the `'paragraph'` button. It can be used together with
+ * {@link module:heading/headingbuttonsui~HeadingButtonsUI} to replace the standard heading dropdown.
+ *
+ * This plugin is not loaded automatically by the {@link module:paragraph/paragraph~Paragraph} plugin. It must
+ * be added manually.
+ *
+ * ```ts
+ * ClassicEditor
+ *   .create( {
+ *     plugins: [ ..., Heading, Paragraph, HeadingButtonsUI, ParagraphButtonUI ]
+ *     toolbar: [ 'paragraph', 'heading1', 'heading2', 'heading3' ]
+ *   } )
+ *   .then( ... )
+ *   .catch( ... );
+ * ```
+ */
+export default class ParagraphButtonUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/src/paragraphbuttonui.js

@@ -16,15 +16,15 @@ const icon = icons.paragraph;
  * This plugin is not loaded automatically by the {@link module:paragraph/paragraph~Paragraph} plugin. It must
  * be added manually.
  *
- *		ClassicEditor
- *			.create( {
- *				plugins: [ ..., Heading, Paragraph, HeadingButtonsUI, ParagraphButtonUI ]
- *				toolbar: [ 'paragraph', 'heading1', 'heading2', 'heading3' ]
- *			} )
- *			.then( ... )
- *			.catch( ... );
- *
- * @extends module:core/plugin~Plugin
+ * ```ts
+ * ClassicEditor
+ *   .create( {
+ *     plugins: [ ..., Heading, Paragraph, HeadingButtonsUI, ParagraphButtonUI ]
+ *     toolbar: [ 'paragraph', 'heading1', 'heading2', 'heading3' ]
+ *   } )
+ *   .then( ... )
+ *   .catch( ... );
+ * ```
  */
 export default class ParagraphButtonUI extends Plugin {
     /**

package/src/paragraphcommand.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @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 paragraph/paragraphcommand
+ */
+import { Command } from '@ckeditor/ckeditor5-core';
+import type { Selection, DocumentSelection } from '@ckeditor/ckeditor5-engine';
+/**
+ * The paragraph command.
+ */
+export default class ParagraphCommand extends Command {
+    /**
+     * The value of the command. Indicates whether the selection start is placed in a paragraph.
+     *
+     * @readonly
+     * @observable
+     */
+    value: boolean;
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command. All the blocks (see {@link module:engine/model/schema~Schema}) in the selection
+     * will be turned to paragraphs.
+     *
+     * @fires execute
+     * @param options Options for the executed command.
+     * @param options.selection The selection that the command should be applied to. By default,
+     * if not provided, the command is applied to the {@link module:engine/model/document~Document#selection}.
+     */
+    execute(options?: {
+        selection?: Selection | DocumentSelection;
+    }): void;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface CommandsMap {
+        paragraph: ParagraphCommand;
+    }
+}

package/src/paragraphcommand.js

@@ -9,8 +9,6 @@ import { Command } from '@ckeditor/ckeditor5-core';
 import { first } from '@ckeditor/ckeditor5-utils';
 /**
  * The paragraph command.
- *
- * @extends module:core/command~Command
  */
 export default class ParagraphCommand extends Command {
     /**
@@ -28,10 +26,9 @@ export default class ParagraphCommand extends Command {
      * will be turned to paragraphs.
      *
      * @fires execute
-     * @param {Object} [options] Options for the executed command.
-     * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} [options.selection]
-     * The selection that the command should be applied to.
-     * By default, if not provided, the command is applied to the {@link module:engine/model/document~Document#selection}.
+     * @param options Options for the executed command.
+     * @param options.selection The selection that the command should be applied to. By default,
+     * if not provided, the command is applied to the {@link module:engine/model/document~Document#selection}.
      */
     execute(options = {}) {
         const model = this.editor.model;
@@ -46,12 +43,12 @@ export default class ParagraphCommand extends Command {
         });
     }
 }
-// Checks whether the given block can be replaced by a paragraph.
-//
-// @private
-// @param {module:engine/model/element~Element} block A block to be tested.
-// @param {module:engine/model/schema~Schema} schema The schema of the document.
-// @returns {Boolean}
+/**
+ * Checks whether the given block can be replaced by a paragraph.
+ *
+ * @param block A block to be tested.
+ * @param schema The schema of the document.
+ */
 function checkCanBecomeParagraph(block, schema) {
     return schema.checkChild(block.parent, 'paragraph') && !schema.isObject(block);
 }