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

package/package.json

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

package/src/enter.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @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 enter/enter
+ */
+import { Plugin } from '@ckeditor/ckeditor5-core';
+/**
+ * This plugin handles the <kbd>Enter</kbd> keystroke (hard line break) in the editor.
+ *
+ * See also the {@link module:enter/shiftenter~ShiftEnter} plugin.
+ *
+ * For more information about this feature see the {@glink api/enter package page}.
+ */
+export default class Enter extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'Enter';
+    init(): void;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [Enter.pluginName]: Enter;
+    }
+}

package/src/enter.js

@@ -14,8 +14,6 @@ import EnterObserver from './enterobserver';
  * See also the {@link module:enter/shiftenter~ShiftEnter} plugin.
  *
  * For more information about this feature see the {@glink api/enter package page}.
- *
- * @extends module:core/plugin~Plugin
  */
 export default class Enter extends Plugin {
     /**

package/src/entercommand.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
+ */
+/**
+ * @module enter/entercommand
+ */
+import { Command } from '@ckeditor/ckeditor5-core';
+import type { Writer } from '@ckeditor/ckeditor5-engine';
+/**
+ * Enter command used by the {@link module:enter/enter~Enter Enter feature} to handle the <kbd>Enter</kbd> keystroke.
+ */
+export default class EnterCommand extends Command {
+    /**
+     * @inheritDoc
+     */
+    execute(): void;
+    /**
+     * Splits a block where the document selection is placed, in the way how the <kbd>Enter</kbd> key is expected to work:
+     *
+     * ```
+     * <p>Foo[]bar</p>   ->   <p>Foo</p><p>[]bar</p>
+     * <p>Foobar[]</p>   ->   <p>Foobar</p><p>[]</p>
+     * <p>Fo[ob]ar</p>   ->   <p>Fo</p><p>[]ar</p>
+     * ```
+     *
+     * In some cases, the split will not happen:
+     *
+     * ```
+     * // The selection parent is a limit element:
+     * <figcaption>A[bc]d</figcaption>   ->   <figcaption>A[]d</figcaption>
+     *
+     * // The selection spans over multiple elements:
+     * <h>x[x</h><p>y]y<p>   ->   <h>x</h><p>[]y</p>
+     * ```
+     *
+     * @param writer Writer to use when performing the enter action.
+     * @returns Boolean indicating if the block was split.
+     */
+    enterBlock(writer: Writer): boolean;
+}
+/**
+ * Fired after the the {@link module:enter/entercommand~EnterCommand} is finished executing.
+ *
+ * @eventName afterExecute
+ */
+export type EnterCommandAfterExecuteEvent = {
+    name: 'afterExecute';
+    args: [{
+        writer: Writer;
+    }];
+};
+declare module '@ckeditor/ckeditor5-core' {
+    interface CommandsMap {
+        enter: EnterCommand;
+    }
+}

package/src/entercommand.js

@@ -8,9 +8,7 @@
 import { Command } from '@ckeditor/ckeditor5-core';
 import { getCopyOnEnterAttributes } from './utils';
 /**
- * Enter command. It is used by the {@link module:enter/enter~Enter Enter feature} to handle the <kbd>Enter</kbd> keystroke.
- *
- * @extends module:core/command~Command
+ * Enter command used by the {@link module:enter/enter~Enter Enter feature} to handle the <kbd>Enter</kbd> keystroke.
  */
 export default class EnterCommand extends Command {
     /**
@@ -25,20 +23,24 @@ export default class EnterCommand extends Command {
     /**
      * Splits a block where the document selection is placed, in the way how the <kbd>Enter</kbd> key is expected to work:
      *
-     *		<p>Foo[]bar</p>   ->   <p>Foo</p><p>[]bar</p>
-     *		<p>Foobar[]</p>   ->   <p>Foobar</p><p>[]</p>
-     *		<p>Fo[ob]ar</p>   ->   <p>Fo</p><p>[]ar</p>
+     * ```
+     * <p>Foo[]bar</p>   ->   <p>Foo</p><p>[]bar</p>
+     * <p>Foobar[]</p>   ->   <p>Foobar</p><p>[]</p>
+     * <p>Fo[ob]ar</p>   ->   <p>Fo</p><p>[]ar</p>
+     * ```
      *
      * In some cases, the split will not happen:
      *
-     *        // The selection parent is a limit element:
-     *        <figcaption>A[bc]d</figcaption>   ->   <figcaption>A[]d</figcaption>
+     * ```
+     * // The selection parent is a limit element:
+     * <figcaption>A[bc]d</figcaption>   ->   <figcaption>A[]d</figcaption>
      *
-     *        // The selection spans over multiple elements:
-     *        <h>x[x</h><p>y]y<p>   ->   <h>x</h><p>[]y</p>
+     * // The selection spans over multiple elements:
+     * <h>x[x</h><p>y]y<p>   ->   <h>x</h><p>[]y</p>
+     * ```
      *
      * @param writer Writer to use when performing the enter action.
-     * @returns `true` if a block was split, `false` otherwise.
+     * @returns Boolean indicating if the block was split.
      */
     enterBlock(writer) {
         const model = this.editor.model;

package/src/enterobserver.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @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 enter/enterobserver
+ */
+import { Observer, DomEventData, type View, type BubblingEvent } from '@ckeditor/ckeditor5-engine';
+/**
+ * Enter observer introduces the {@link module:engine/view/document~Document#event:enter `Document#enter`} event.
+ */
+export default class EnterObserver extends Observer {
+    /**
+     * @inheritDoc
+     */
+    constructor(view: View);
+    /**
+     * @inheritDoc
+     */
+    observe(): void;
+}
+/**
+ * Fired when the user presses the <kbd>Enter</kbd> key.
+ *
+ * Note: This event is fired by the {@link module:enter/enterobserver~EnterObserver observer}
+ * (usually registered by the {@link module:enter/enter~Enter Enter feature} and
+ * {@link module:enter/shiftenter~ShiftEnter ShiftEnter feature}).
+ *
+ * @eventName enter
+ */
+export type ViewDocumentEnterEvent = BubblingEvent<{
+    name: 'enter';
+    args: [EnterEventData];
+}>;
+export interface EnterEventData extends DomEventData<InputEvent> {
+    /**
+     * Whether it is a soft enter (<kbd>Shift</kbd>+<kbd>Enter</kbd>) or a hard enter (<kbd>Enter</kbd>).
+     */
+    isSoft: boolean;
+}

package/src/enterobserver.js

@@ -12,8 +12,6 @@ const ENTER_EVENT_TYPES = {
 };
 /**
  * Enter observer introduces the {@link module:engine/view/document~Document#event:enter `Document#enter`} event.
- *
- * @extends module:engine/view/observer/observer~Observer
  */
 export default class EnterObserver extends Observer {
     /**

package/src/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @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 enter
+ */
+export { default as Enter } from './enter';
+export { default as ShiftEnter } from './shiftenter';
+export type { ViewDocumentEnterEvent } from './enterobserver';
+export type { default as EnterCommand } from './entercommand';
+export type { default as ShiftEnterCommand } from './shiftentercommand';

package/src/shiftenter.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @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';
+/**
+ * This plugin handles the <kbd>Shift</kbd>+<kbd>Enter</kbd> keystroke (soft line break) in the editor.
+ *
+ * See also the {@link module:enter/enter~Enter} plugin.
+ *
+ * For more information about this feature see the {@glink api/enter package page}.
+ */
+export default class ShiftEnter extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'ShiftEnter';
+    init(): void;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [ShiftEnter.pluginName]: ShiftEnter;
+    }
+}

package/src/shiftenter.js

@@ -14,8 +14,6 @@ import { Plugin } from '@ckeditor/ckeditor5-core';
  * See also the {@link module:enter/enter~Enter} plugin.
  *
  * For more information about this feature see the {@glink api/enter package page}.
- *
- * @extends module:core/plugin~Plugin
  */
 export default class ShiftEnter extends Plugin {
     /**

package/src/shiftentercommand.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @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 enter/shiftentercommand
+ */
+import { Command } from '@ckeditor/ckeditor5-core';
+import type { Writer } from '@ckeditor/ckeditor5-engine';
+/**
+ * ShiftEnter command. It is used by the {@link module:enter/shiftenter~ShiftEnter ShiftEnter feature} to handle
+ * the <kbd>Shift</kbd>+<kbd>Enter</kbd> keystroke.
+ */
+export default class ShiftEnterCommand extends Command {
+    /**
+     * @inheritDoc
+     */
+    execute(): void;
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+}
+/**
+ * Fired after the the {@link module:enter/shiftentercommand~ShiftEnterCommand} is finished executing.
+ *
+ * @eventName afterExecute
+ */
+export type ShiftEnterCommandAfterExecuteEvent = {
+    name: 'afterExecute';
+    args: [{
+        writer: Writer;
+    }];
+};
+declare module '@ckeditor/ckeditor5-core' {
+    interface CommandsMap {
+        shiftEnter: ShiftEnterCommand;
+    }
+}

package/src/shiftentercommand.js

@@ -10,8 +10,6 @@ import { getCopyOnEnterAttributes } from './utils';
 /**
  * ShiftEnter command. It is used by the {@link module:enter/shiftenter~ShiftEnter ShiftEnter feature} to handle
  * the <kbd>Shift</kbd>+<kbd>Enter</kbd> keystroke.
- *
- * @extends module:core/command~Command
  */
 export default class ShiftEnterCommand extends Command {
     /**
@@ -25,16 +23,18 @@ export default class ShiftEnterCommand extends Command {
             this.fire('afterExecute', { writer });
         });
     }
+    /**
+     * @inheritDoc
+     */
     refresh() {
         const model = this.editor.model;
         const doc = model.document;
         this.isEnabled = isEnabled(model.schema, doc.selection);
     }
 }
-// Checks whether the ShiftEnter command should be enabled in the specified selection.
-//
-// @param {module:engine/model/schema~Schema} schema
-// @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
+/**
+ * Checks whether the ShiftEnter command should be enabled in the specified selection.
+ */
 function isEnabled(schema, selection) {
     // At this moment it is okay to support single range selections only.
     // But in the future we may need to change that.
@@ -55,12 +55,9 @@ function isEnabled(schema, selection) {
     }
     return true;
 }
-// Creates a break in the way that the <kbd>Shift</kbd>+<kbd>Enter</kbd> keystroke is expected to work.
-//
-// @param {module:engine/model~Model} model
-// @param {module:engine/model/writer~Writer} writer
-// @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
-// Selection on which the action should be performed.
+/**
+ * Creates a break in the way that the <kbd>Shift</kbd>+<kbd>Enter</kbd> keystroke is expected to work.
+ */
 function softBreakAction(model, writer, selection) {
     const isSelectionEmpty = selection.isCollapsed;
     const range = selection.getFirstRange();
@@ -105,15 +102,13 @@ function insertBreak(model, writer, position) {
     model.insertContent(breakLineElement, position);
     writer.setSelection(breakLineElement, 'after');
 }
-// Checks whether the specified `element` is a child of the limit element.
-//
-// Checking whether the `<p>` element is inside a limit element:
-//   - <$root><p>Text.</p></$root> => false
-//   - <$root><limitElement><p>Text</p></limitElement></$root> => true
-//
-// @param {module:engine/model/element~Element} element
-// @param {module:engine/schema~Schema} schema
-// @returns {Boolean}
+/**
+ * Checks whether the specified `element` is a child of the limit element.
+ *
+ * Checking whether the `<p>` element is inside a limit element:
+ *   - `<$root><p>Text.</p></$root> => false`
+ *   - `<$root><limitElement><p>Text</p></limitElement></$root> => true`
+ */
 function isInsideLimitElement(element, schema) {
     // `$root` is a limit element but in this case is an invalid element.
     if (element.is('rootElement')) {

package/src/utils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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 enter/utils
+ */
+import type { Schema } from '@ckeditor/ckeditor5-engine';
+/**
+ * Returns attributes that should be preserved on the enter keystroke.
+ *
+ * Filtering is realized based on `copyOnEnter` attribute property. Read more about attribute properties
+ * {@link module:engine/model/schema~Schema#setAttributeProperties here}.
+ *
+ * @param schema Model's schema.
+ * @param allAttributes Attributes to filter.
+ */
+export declare function getCopyOnEnterAttributes(schema: Schema, allAttributes: Iterable<[string, unknown]>): IterableIterator<[string, unknown]>;

package/src/utils.js

@@ -8,9 +8,8 @@
  * Filtering is realized based on `copyOnEnter` attribute property. Read more about attribute properties
  * {@link module:engine/model/schema~Schema#setAttributeProperties here}.
  *
- * @param {module:engine/model/schema~Schema} schema
- * @param {Iterable.<*>} allAttributes attributes to filter.
- * @returns {Iterable.<*>}
+ * @param schema Model's schema.
+ * @param allAttributes Attributes to filter.
  */
 export function* getCopyOnEnterAttributes(schema, allAttributes) {
     for (const attribute of allAttributes) {