@ckeditor/ckeditor5-code-block 36.0.1 → 37.0.0-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-code-block",
-  "version": "36.0.1",
+  "version": "37.0.0-alpha.1",
   "description": "Code block feature for CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -12,27 +12,27 @@
   ],
   "main": "src/index.js",
   "dependencies": {
-    "ckeditor5": "^36.0.1"
+    "ckeditor5": "^37.0.0-alpha.1"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-alignment": "^36.0.1",
-    "@ckeditor/ckeditor5-autoformat": "^36.0.1",
-    "@ckeditor/ckeditor5-basic-styles": "^36.0.1",
-    "@ckeditor/ckeditor5-block-quote": "^36.0.1",
-    "@ckeditor/ckeditor5-clipboard": "^36.0.1",
-    "@ckeditor/ckeditor5-core": "^36.0.1",
-    "@ckeditor/ckeditor5-dev-utils": "^32.0.0",
-    "@ckeditor/ckeditor5-engine": "^36.0.1",
-    "@ckeditor/ckeditor5-enter": "^36.0.1",
-    "@ckeditor/ckeditor5-editor-classic": "^36.0.1",
-    "@ckeditor/ckeditor5-image": "^36.0.1",
-    "@ckeditor/ckeditor5-indent": "^36.0.1",
-    "@ckeditor/ckeditor5-list": "^36.0.1",
-    "@ckeditor/ckeditor5-markdown-gfm": "^36.0.1",
-    "@ckeditor/ckeditor5-paragraph": "^36.0.1",
-    "@ckeditor/ckeditor5-theme-lark": "^36.0.1",
-    "@ckeditor/ckeditor5-undo": "^36.0.1",
-    "@ckeditor/ckeditor5-utils": "^36.0.1",
+    "@ckeditor/ckeditor5-alignment": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-autoformat": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-basic-styles": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-block-quote": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-clipboard": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-core": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-dev-utils": "^35.0.0",
+    "@ckeditor/ckeditor5-engine": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-enter": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-editor-classic": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-image": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-indent": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-list": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-markdown-gfm": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-paragraph": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-theme-lark": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-undo": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-utils": "^37.0.0-alpha.1",
     "typescript": "^4.8.4",
     "webpack": "^5.58.1",
     "webpack-cli": "^4.9.0"
@@ -61,7 +61,8 @@
   ],
   "scripts": {
     "dll:build": "webpack",
-    "build": "tsc -p ./tsconfig.release.json",
+    "build": "tsc -p ./tsconfig.json",
     "postversion": "npm run build"
-  }
+  },
+  "types": "src/index.d.ts"
 }

package/src/augmentation.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @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 { CodeBlock, CodeBlockCommand, CodeBlockConfig, CodeBlockEditing, CodeBlockUI, IndentCodeBlockCommand, OutdentCodeBlockCommand } from './index';
+declare module '@ckeditor/ckeditor5-core' {
+    interface EditorConfig {
+        /**
+         * The configuration of the {@link module:code-block/codeblock~CodeBlock} feature.
+         *
+         * Read more in {@link module:code-block/codeblockconfig~CodeBlockConfig}.
+         */
+        codeBlock?: CodeBlockConfig;
+    }
+    interface PluginsMap {
+        [CodeBlock.pluginName]: CodeBlock;
+        [CodeBlockEditing.pluginName]: CodeBlockEditing;
+        [CodeBlockUI.pluginName]: CodeBlockUI;
+    }
+    interface CommandsMap {
+        codeBlock: CodeBlockCommand;
+        indentCodeBlock: IndentCodeBlockCommand;
+        outdentCodeBlock: OutdentCodeBlockCommand;
+    }
+}

package/src/augmentation.js

@@ -0,0 +1,5 @@
+/**
+ * @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
+ */
+export {};

package/src/codeblock.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 code-block/codeblock
+ */
+import { Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+/**
+ * The code block plugin.
+ *
+ * For more information about this feature check the {@glink api/code-block package page} and the
+ * {@glink features/code-blocks code block} feature guide.
+ *
+ * This is a "glue" plugin that loads the {@link module:code-block/codeblockediting~CodeBlockEditing code block editing feature}
+ * and the {@link module:code-block/codeblockui~CodeBlockUI code block UI feature}.
+ */
+export default class CodeBlock extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'CodeBlock';
+}

package/src/codeblock.js

@@ -12,7 +12,7 @@ import CodeBlockUI from './codeblockui';
  * The code block plugin.
  *
  * For more information about this feature check the {@glink api/code-block package page} and the
- * {@glink features/code-blocks code block feature guide}.
+ * {@glink features/code-blocks code block} feature guide.
  *
  * This is a "glue" plugin that loads the {@link module:code-block/codeblockediting~CodeBlockEditing code block editing feature}
  * and the {@link module:code-block/codeblockui~CodeBlockUI code block UI feature}.

package/src/codeblockcommand.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @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 { Command, type Editor } from 'ckeditor5/src/core';
+/**
+ * The code block command plugin.
+ */
+export default class CodeBlockCommand extends Command {
+    /**
+     * Contains the last used language.
+     */
+    private _lastLanguage;
+    /**
+     * Contains language if any is selected, false otherwise.
+     * @observable
+     * @readonly
+     */
+    value: string | false;
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command. When the command {@link #value is on}, all topmost code blocks within
+     * the selection will be removed. If it is off, all selected blocks will be flattened and
+     * wrapped by a code block.
+     *
+     * @fires execute
+     * @param options Command options.
+     * @param options.language The code block language.
+     * @param options.forceValue If set, it will force the command behavior. If `true`, the command will apply a code block,
+     * otherwise the command will remove the code block. If not set, the command will act basing on its current value.
+     * @param options.usePreviousLanguageChoice If set on `true` and the `options.language` is not specified, the command
+     * will apply the previous language (if the command was already executed) when inserting the `codeBlock` element.
+     */
+    execute(options?: {
+        language?: string;
+        forceValue?: boolean;
+        usePreviousLanguageChoice?: boolean;
+    }): void;
+    /**
+     * Checks the command's {@link #value}.
+     *
+     * @returns The current value.
+     */
+    private _getValue;
+    /**
+     * Checks whether the command can be enabled in the current context.
+     *
+     * @returns Whether the command should be enabled.
+     */
+    private _checkEnabled;
+    private _applyCodeBlock;
+    private _removeCodeBlock;
+}

package/src/codeblockconfig.d.ts

@@ -0,0 +1,146 @@
+/**
+ * @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 code-block/codeblockconfig
+ */
+/**
+ * The configuration of the {@link module:code-block/codeblock~CodeBlock code block feature}.
+ *
+ * ```ts
+ * ClassicEditor
+ * 	.create( editorElement, {
+ * 		codeBlock:  ... // The code block feature configuration.
+ * 	} )
+ * 	.then( ... )
+ * 	.catch( ... );
+ * ```
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ */
+export interface CodeBlockConfig {
+    /**
+     * The list of code languages available in the user interface to choose for a particular code block.
+     *
+     * The language of the code block is represented as a CSS class (by default prefixed by "language-") set on the
+     * `<code>` element, both when editing and in the editor data. The CSS class associated with the language
+     * can be used by third–party code syntax highlighters to detect and apply the correct highlighting.
+     *
+     * For instance, this language configuration:
+     *
+     * ```ts
+     * ClassicEditor
+     * 	.create( document.querySelector( '#editor' ), {
+     * 		codeBlock: {
+     * 			languages: [
+     * 				// ...
+     * 				{ language: 'javascript', label: 'JavaScript' },
+     * 				// ...
+     * 			]
+     * 		}
+     * 	} )
+     * 	.then( ... )
+     * 	.catch( ... );
+     * ```
+     *
+     * will result in the following structure of JavaScript code blocks in the editor editing and data:
+     *
+     * ```html
+     * <pre><code class="language-javascript">window.alert( 'Hello world!' )</code></pre>
+     * ```
+     *
+     * You can customize the CSS class by specifying an optional `class` property in the language definition.
+     * You can set **multiple classes** but **only the first one** will be used as defining language class:
+     *
+     * ```ts
+     * ClassicEditor
+     * 	.create( document.querySelector( '#editor' ), {
+     * 		codeBlock: {
+     * 			languages: [
+     * 				// Do not render the CSS class for the plain text code blocks.
+     * 				{ language: 'plaintext', label: 'Plain text', class: '' },
+     *
+     * 				// Use the "php-code" class for PHP code blocks.
+     * 				{ language: 'php', label: 'PHP', class: 'php-code' },
+     *
+     * 				// Use the "js" class for JavaScript code blocks.
+     * 				// Note that only the first ("js") class will determine the language of the block when loading data.
+     * 				{ language: 'javascript', label: 'JavaScript', class: 'js javascript js-code' },
+     *
+     * 				// Python code blocks will have the default "language-python" CSS class.
+     * 				{ language: 'python', label: 'Python' }
+     * 			]
+     * 		}
+     * } )
+     * .then( ... )
+     * .catch( ... );
+     * ```
+     *
+     * The default value of the language configuration is as follows:
+     *
+     * ```ts
+     * languages: [
+     * 	{ language: 'plaintext', label: 'Plain text' }, // The default language.
+     * 	{ language: 'c', label: 'C' },
+     * 	{ language: 'cs', label: 'C#' },
+     * 	{ language: 'cpp', label: 'C++' },
+     * 	{ language: 'css', label: 'CSS' },
+     * 	{ language: 'diff', label: 'Diff' },
+     * 	{ language: 'html', label: 'HTML' },
+     * 	{ language: 'java', label: 'Java' },
+     * 	{ language: 'javascript', label: 'JavaScript' },
+     * 	{ language: 'php', label: 'PHP' },
+     * 	{ language: 'python', label: 'Python' },
+     * 	{ language: 'ruby', label: 'Ruby' },
+     * 	{ language: 'typescript', label: 'TypeScript' },
+     * 	{ language: 'xml', label: 'XML' }
+     * ]
+     * ```
+     *
+     * **Note**: The first language defined in the configuration is considered the default one. This means it will be
+     * applied to code blocks loaded from the data that have no CSS `class` specified (or no matching `class` in the configuration).
+     * It will also be used when creating new code blocks using the main UI button. By default it is "Plain text".
+     */
+    languages?: Array<CodeBlockLanguageDefinition>;
+    /**
+     * A sequence of characters inserted or removed from the code block lines when its indentation
+     * is changed by the user, for instance, using <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys.
+     *
+     * The default value is a single tab character ("	", `\u0009` in Unicode).
+     *
+     * This configuration is used by `indentCodeBlock` and `outdentCodeBlock` commands (instances of
+     * {@link module:code-block/indentcodeblockcommand~IndentCodeBlockCommand}).
+     *
+     * **Note**: Setting this configuration to `false` will disable the code block indentation commands
+     * and associated keystrokes.
+     *
+     */
+    indentSequence?: string;
+}
+/**
+ * The code block language descriptor. See {@link module:code-block/codeblockconfig~CodeBlockConfig#languages} to learn more.
+ *
+ * ```ts
+ * {
+ * 	language: 'javascript',
+ * 	label: 'JavaScript'
+ * }
+ * ```
+ */
+export interface CodeBlockLanguageDefinition {
+    /**
+     * The name of the language that will be stored in the model attribute. Also, when `class`
+     * is not specified, it will be used to create the CSS class associated with the language (prefixed by "language-").
+     */
+    language: string;
+    /**
+     * The human–readable label associated with the language and displayed in the UI.
+     */
+    label: string;
+    /**
+     * The CSS class associated with the language. When not specified the `language`
+     * property is used to create a class prefixed by "language-".
+     */
+    class?: string;
+}

package/src/codeblockconfig.js

@@ -0,0 +1,5 @@
+/**
+ * @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
+ */
+export {};

package/src/codeblockediting.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 code-block/codeblockediting
+ */
+import { Plugin, type PluginDependencies, type Editor } from 'ckeditor5/src/core';
+/**
+ * The editing part of the code block feature.
+ *
+ * Introduces the `'codeBlock'` command and the `'codeBlock'` model element.
+ */
+export default class CodeBlockEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'CodeBlockEditing';
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    afterInit(): void;
+}

package/src/codeblockui.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @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 code-block/codeblockui
+ */
+import { Plugin } from 'ckeditor5/src/core';
+import '../theme/codeblock.css';
+/**
+ * The code block UI plugin.
+ *
+ * Introduces the `'codeBlock'` dropdown.
+ */
+export default class CodeBlockUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'CodeBlockUI';
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * A helper returning a collection of the `codeBlock` dropdown items representing languages
+     * available for the user to choose from.
+     */
+    private _getLanguageListItemDefinitions;
+}

package/src/converters.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @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 code-block/converters
+ */
+import type { GetCallback } from 'ckeditor5/src/utils';
+import type { DowncastInsertEvent, Model, UpcastElementEvent, UpcastTextEvent, View } from 'ckeditor5/src/engine';
+import type { CodeBlockLanguageDefinition } from './codeblockconfig';
+/**
+ * A model-to-view (both editing and data) converter for the `codeBlock` element.
+ *
+ * Sample input:
+ *
+ * ```html
+ * <codeBlock language="javascript">foo();<softBreak></softBreak>bar();</codeBlock>
+ * ```
+ *
+ * Sample output (editing):
+ *
+ * ```html
+ * <pre data-language="JavaScript"><code class="language-javascript">foo();<br />bar();</code></pre>
+ * ```
+ *
+ * Sample output (data, see {@link module:code-block/converters~modelToDataViewSoftBreakInsertion}):
+ *
+ * ```html
+ * <pre><code class="language-javascript">foo();\nbar();</code></pre>
+ * ```
+ *
+ * @param languageDefs The normalized language configuration passed to the feature.
+ * @param useLabels When `true`, the `<pre>` element will get a `data-language` attribute with a
+ * human–readable label of the language. Used only in the editing.
+ * @returns Returns a conversion callback.
+ */
+export declare function modelToViewCodeBlockInsertion(model: Model, languageDefs: Array<CodeBlockLanguageDefinition>, useLabels?: boolean): GetCallback<DowncastInsertEvent>;
+/**
+ * A model-to-data view converter for the new line (`softBreak`) separator.
+ *
+ * Sample input:
+ *
+ * ```html
+ * <codeBlock ...>foo();<softBreak></softBreak>bar();</codeBlock>
+ * ```
+ *
+ * Sample output:
+ *
+ * ```html
+ * <pre><code ...>foo();\nbar();</code></pre>
+ * ```
+ *
+ * @returns Returns a conversion callback.
+ */
+export declare function modelToDataViewSoftBreakInsertion(model: Model): GetCallback<DowncastInsertEvent>;
+/**
+ * A view-to-model converter for `<pre>` with the `<code>` HTML.
+ *
+ * Sample input:
+ *
+ * ```html
+ * <pre><code class="language-javascript">foo();bar();</code></pre>
+ * ```
+ *
+ * Sample output:
+ *
+ * ```html
+ * <codeBlock language="javascript">foo();bar();</codeBlock>
+ * ```
+ *
+ * @param languageDefs The normalized language configuration passed to the feature.
+ * @returns Returns a conversion callback.
+ */
+export declare function dataViewToModelCodeBlockInsertion(editingView: View, languageDefs: Array<CodeBlockLanguageDefinition>): GetCallback<UpcastElementEvent>;
+/**
+ * A view-to-model converter for new line characters in `<pre>`.
+ *
+ * Sample input:
+ *
+ * ```html
+ * <pre><code class="language-javascript">foo();\nbar();</code></pre>
+ * ```
+ *
+ * Sample output:
+ *
+ * ```html
+ * <codeBlock language="javascript">foo();<softBreak></softBreak>bar();</codeBlock>
+ * ```
+ *
+ * @returns {Function} Returns a conversion callback.
+ */
+export declare function dataViewToModelTextNewlinesInsertion(): GetCallback<UpcastTextEvent>;
+/**
+ * A view-to-model converter that handles orphan text nodes (white spaces, new lines, etc.)
+ * that surround `<code>` inside `<pre>`.
+ *
+ * Sample input:
+ *
+ * ```html
+ * // White spaces
+ * <pre> <code>foo()</code> </pre>
+ *
+ * // White spaces
+ * <pre>      <code>foo()</code>      </pre>
+ *
+ * // White spaces
+ * <pre>			<code>foo()</code>			</pre>
+ *
+ * // New lines
+ * <pre>
+ * 	<code>foo()</code>
+ * </pre>
+ *
+ * // Redundant text
+ * <pre>ABC<code>foo()</code>DEF</pre>
+ * ```
+ *
+ * Unified output for each case:
+ *
+ * ```html
+ * <codeBlock language="plaintext">foo()</codeBlock>
+ * ```
+ *
+ * @returns Returns a conversion callback.
+ */
+export declare function dataViewToModelOrphanNodeConsumer(): GetCallback<UpcastElementEvent>;

package/src/indentcodeblockcommand.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @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 code-block/indentcodeblockcommand
+ */
+import { Command, type Editor } from 'ckeditor5/src/core';
+/**
+ * The code block indentation increase command plugin.
+ */
+export default class IndentCodeBlockCommand extends Command {
+    /**
+     * A sequence of characters added to the line when the command is executed.
+     */
+    private _indentSequence;
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command. When the command {@link #isEnabled is enabled}, the indentation of the
+     * code lines in the selection will be increased.
+     *
+     * @fires execute
+     */
+    execute(): void;
+    /**
+     * Checks whether the command can be enabled in the current context.
+     */
+    private _checkEnabled;
+}

package/src/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @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 code-block
+ */
+export { default as CodeBlock } from './codeblock';
+export { default as CodeBlockEditing } from './codeblockediting';
+export { default as CodeBlockUI } from './codeblockui';
+export type { default as CodeBlockCommand } from './codeblockcommand';
+export type { default as IndentCodeBlockCommand } from './indentcodeblockcommand';
+export type { default as OutdentCodeBlockCommand } from './outdentcodeblockcommand';
+export type { CodeBlockConfig } from './codeblockconfig';
+import './augmentation';

package/src/index.js

@@ -8,3 +8,4 @@
 export { default as CodeBlock } from './codeblock';
 export { default as CodeBlockEditing } from './codeblockediting';
 export { default as CodeBlockUI } from './codeblockui';
+import './augmentation';

package/src/outdentcodeblockcommand.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @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 { Command, type Editor } from 'ckeditor5/src/core';
+/**
+ * The code block indentation decrease command plugin.
+ */
+export default class OutdentCodeBlockCommand extends Command {
+    /**
+     * A sequence of characters removed from the line when the command is executed.
+     */
+    private readonly _indentSequence;
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command. When the command {@link #isEnabled is enabled}, the indentation of the
+     * code lines in the selection will be decreased.
+     *
+     * @fires execute
+     */
+    execute(): void;
+    /**
+     * Checks whether the command can be enabled in the current context.
+     *
+     * @private
+     * @returns {Boolean} Whether the command should be enabled.
+     */
+    private _checkEnabled;
+}

package/src/utils.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
+ */
+/**
+ * @module code-block/utils
+ */
+import type { Editor } from 'ckeditor5/src/core';
+import type { CodeBlockLanguageDefinition } from './codeblockconfig';
+import type { DocumentSelection, Element, Model, Position, Schema, Text, UpcastWriter, ViewDocumentFragment } from 'ckeditor5/src/engine';
+/**
+ * Returns code block languages as defined in `config.codeBlock.languages` but processed:
+ *
+ * * To consider the editor localization, i.e. to display {@link module:code-block/codeblockconfig~CodeBlockLanguageDefinition}
+ * in the correct language. There is no way to use {@link module:utils/locale~Locale#t} when the user
+ * configuration is defined because the editor does not exist yet.
+ * * To make sure each definition has a CSS class associated with it even if not specified
+ * in the original configuration.
+ */
+export declare function getNormalizedAndLocalizedLanguageDefinitions(editor: Editor): Array<CodeBlockLanguageDefinition>;
+/**
+ * Returns an object associating certain language definition properties with others. For instance:
+ *
+ * For:
+ *
+ * ```ts
+ * const definitions = {
+ * 	{ language: 'php', class: 'language-php', label: 'PHP' },
+ * 	{ language: 'javascript', class: 'js', label: 'JavaScript' },
+ * };
+ *
+ * getPropertyAssociation( definitions, 'class', 'language' );
+ * ```
+ *
+ * returns:
+ *
+ * ```ts
+ * {
+ * 	'language-php': 'php',
+ * 	'js': 'javascript'
+ * }
+ * ```
+ *
+ * and
+ *
+ * ```ts
+ * getPropertyAssociation( definitions, 'language', 'label' );
+ * ```
+ *
+ * returns:
+ *
+ * ```ts
+ * {
+ * 	'php': 'PHP',
+ * 	'javascript': 'JavaScript'
+ * }
+ * ```
+ */
+export declare function getPropertyAssociation(languageDefs: Array<CodeBlockLanguageDefinition>, key: keyof CodeBlockLanguageDefinition, value: keyof CodeBlockLanguageDefinition): Record<string, string>;
+/**
+ * For a given model text node, it returns white spaces that precede other characters in that node.
+ * This corresponds to the indentation part of the code block line.
+ */
+export declare function getLeadingWhiteSpaces(textNode: Text): string;
+/**
+ * For plain text containing the code (a snippet), it returns a document fragment containing
+ * view text nodes separated by `<br>` elements (in place of new line characters "\n"), for instance:
+ *
+ * Input:
+ *
+ * ```ts
+ * "foo()\n
+ * bar()"
+ * ```
+ *
+ * Output:
+ *
+ * ```html
+ * <DocumentFragment>
+ * 	"foo()"
+ * 	<br/>
+ * 	"bar()"
+ * </DocumentFragment>
+ * ```
+ *
+ * @param text The raw code text to be converted.
+ */
+export declare function rawSnippetTextToViewDocumentFragment(writer: UpcastWriter, text: string): ViewDocumentFragment;
+/**
+ * Returns an array of all model positions within the selection that represent code block lines.
+ *
+ * If the selection is collapsed, it returns the exact selection anchor position:
+ *
+ * ```html
+ * <codeBlock>[]foo</codeBlock>        ->     <codeBlock>^foo</codeBlock>
+ * <codeBlock>foo[]bar</codeBlock>     ->     <codeBlock>foo^bar</codeBlock>
+ * ```
+ *
+ * Otherwise, it returns positions **before** each text node belonging to all code blocks contained by the selection:
+ *
+ * ```html
+ * <codeBlock>                                <codeBlock>
+ *     foo[bar                                   ^foobar
+ *     <softBreak></softBreak>         ->        <softBreak></softBreak>
+ *     baz]qux                                   ^bazqux
+ * </codeBlock>                               </codeBlock>
+ * ```
+ *
+ * It also works across other non–code blocks:
+ *
+ * ```html
+ * <codeBlock>                                <codeBlock>
+ *     foo[bar                                   ^foobar
+ * </codeBlock>                               </codeBlock>
+ * <paragraph>text</paragraph>         ->     <paragraph>text</paragraph>
+ * <codeBlock>                                <codeBlock>
+ *     baz]qux                                   ^bazqux
+ * </codeBlock>                               </codeBlock>
+ * ```
+ *
+ * **Note:** The positions are in reverse order so they do not get outdated when iterating over them and
+ * the writer inserts or removes elements at the same time.
+ *
+ * **Note:** The position is located after the leading white spaces in the text node.
+ */
+export declare function getIndentOutdentPositions(model: Model): Array<Position>;
+/**
+ * Checks if any of the blocks within the model selection is a code block.
+ */
+export declare function isModelSelectionInCodeBlock(selection: DocumentSelection): boolean;
+/**
+ * Checks if an {@link module:engine/model/element~Element Element} can become a code block.
+ *
+ * @param schema Model's schema.
+ * @param element The element to be checked.
+ * @returns Check result.
+ */
+export declare function canBeCodeBlock(schema: Schema, element: Element): boolean;

package/src/utils.js

@@ -6,7 +6,7 @@ import { first } from 'ckeditor5/src/utils';
 /**
  * Returns code block languages as defined in `config.codeBlock.languages` but processed:
  *
- * * To consider the editor localization, i.e. to display {@link module:code-block/codeblock~CodeBlockLanguageDefinition}
+ * * To consider the editor localization, i.e. to display {@link module:code-block/codeblockconfig~CodeBlockLanguageDefinition}
  * in the correct language. There is no way to use {@link module:utils/locale~Locale#t} when the user
  * configuration is defined because the editor does not exist yet.
  * * To make sure each definition has a CSS class associated with it even if not specified
@@ -30,12 +30,14 @@ export function getNormalizedAndLocalizedLanguageDefinitions(editor) {
  *
  * For:
  *
+ * ```ts
  * const definitions = {
  * 	{ language: 'php', class: 'language-php', label: 'PHP' },
  * 	{ language: 'javascript', class: 'js', label: 'JavaScript' },
  * };
  *
  * getPropertyAssociation( definitions, 'class', 'language' );
+ * ```
  *
  * returns:
  *