@ckeditor/ckeditor5-code-block 41.3.0 → 41.4.0-alpha.0

package/dist/types/codeblockediting.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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 Editor } from 'ckeditor5/src/core.js';
+import { ShiftEnter } from 'ckeditor5/src/enter.js';
+/**
+ * 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(): readonly [typeof ShiftEnter];
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    afterInit(): void;
+    /**
+     * Observe when user enters or leaves code block and set proper aria value in global live announcer.
+     * This allows screen readers to indicate when the user has entered and left the specified code block.
+     *
+     * @internal
+     */
+    private _initAriaAnnouncements;
+}

package/dist/types/codeblockui.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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.js';
+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/dist/types/converters.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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.js';
+import type { DowncastInsertEvent, Model, UpcastElementEvent, UpcastTextEvent, EditingView } from 'ckeditor5/src/engine.js';
+import type { CodeBlockLanguageDefinition } from './codeblockconfig.js';
+/**
+ * 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: EditingView, 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/dist/types/indentcodeblockcommand.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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.js';
+/**
+ * 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/dist/types/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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.js';
+export { default as CodeBlockEditing } from './codeblockediting.js';
+export { default as CodeBlockUI } from './codeblockui.js';
+export type { default as CodeBlockCommand } from './codeblockcommand.js';
+export type { default as IndentCodeBlockCommand } from './indentcodeblockcommand.js';
+export type { default as OutdentCodeBlockCommand } from './outdentcodeblockcommand.js';
+export type { CodeBlockConfig } from './codeblockconfig.js';
+import './augmentation.js';

package/dist/types/outdentcodeblockcommand.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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.js';
+/**
+ * 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/dist/types/utils.d.ts

@@ -0,0 +1,147 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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.js';
+import type { CodeBlockLanguageDefinition } from './codeblockconfig.js';
+import type { DocumentSelection, Element, Model, Position, Schema, Text, UpcastWriter, ViewDocumentFragment } from 'ckeditor5/src/engine.js';
+import { type LocaleTranslate } from 'ckeditor5/src/utils.js';
+/**
+ * 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;
+/**
+ * Get the translated message read by the screen reader when you enter or exit an element with your cursor.
+ */
+export declare function getCodeBlockAriaAnnouncement(t: LocaleTranslate, languageDefs: Array<CodeBlockLanguageDefinition>, element: Element, direction: 'enter' | 'leave'): string;

package/lang/contexts.json

@@ -1,5 +1,9 @@
 {
 	"Insert code block": "A label of the button that allows inserting a new code block into the editor content.",
 	"Plain text": "A language of the code block in the editor content when no specific programming language is associated with it.",
+	"Leaving %0 code snippet": "Assistive technologies label for leaving the code block with a specified programming language. Example: 'Leaving JavaScript code snippet'",
+	"Entering %0 code snippet": "Assistive technologies label for entering the code block with a specified programming language. Example: 'Entering JavaScript code snippet'",
+	"Entering code snippet": "Assistive technologies label for entering the code block with unspecified programming language.",
+	"Leaving code snippet": "Assistive technologies label for leaving the code block with unspecified programming language.",
 	"Code block": "The accessible label of the menu bar button that inserts a code block into editor content."
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-code-block",
-  "version": "41.3.0",
+  "version": "41.4.0-alpha.0",
   "description": "Code block feature for CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -13,7 +13,8 @@
   "type": "module",
   "main": "src/index.js",
   "dependencies": {
-    "ckeditor5": "41.3.0"
+    "ckeditor5": "41.4.0-alpha.0",
+    "lodash-es": "4.17.21"
   },
   "author": "CKSource (http://cksource.com/)",
   "license": "GPL-2.0-or-later",
@@ -25,6 +26,7 @@
     "directory": "packages/ckeditor5-code-block"
   },
   "files": [
+    "dist",
     "lang",
     "src/**/*.js",
     "src/**/*.d.ts",

package/src/codeblockediting.d.ts

@@ -2,9 +2,6 @@
  * @license Copyright (c) 2003-2024, 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 Editor } from 'ckeditor5/src/core.js';
 import { ShiftEnter } from 'ckeditor5/src/enter.js';
 /**
@@ -33,4 +30,11 @@ export default class CodeBlockEditing extends Plugin {
      * @inheritDoc
      */
     afterInit(): void;
+    /**
+     * Observe when user enters or leaves code block and set proper aria value in global live announcer.
+     * This allows screen readers to indicate when the user has entered and left the specified code block.
+     *
+     * @internal
+     */
+    private _initAriaAnnouncements;
 }

package/src/codeblockediting.js

@@ -2,16 +2,13 @@
  * @license Copyright (c) 2003-2024, 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 } from 'ckeditor5/src/core.js';
 import { ShiftEnter } from 'ckeditor5/src/enter.js';
 import { UpcastWriter } from 'ckeditor5/src/engine.js';
 import CodeBlockCommand from './codeblockcommand.js';
 import IndentCodeBlockCommand from './indentcodeblockcommand.js';
 import OutdentCodeBlockCommand from './outdentcodeblockcommand.js';
-import { getNormalizedAndLocalizedLanguageDefinitions, getLeadingWhiteSpaces, rawSnippetTextToViewDocumentFragment } from './utils.js';
+import { getNormalizedAndLocalizedLanguageDefinitions, getLeadingWhiteSpaces, rawSnippetTextToViewDocumentFragment, getCodeBlockAriaAnnouncement } from './utils.js';
 import { modelToViewCodeBlockInsertion, modelToDataViewSoftBreakInsertion, dataViewToModelCodeBlockInsertion, dataViewToModelTextNewlinesInsertion, dataViewToModelOrphanNodeConsumer } from './converters.js';
 const DEFAULT_ELEMENT = 'paragraph';
 /**
@@ -195,6 +192,31 @@ export default class CodeBlockEditing extends Plugin {
             data.preventDefault();
             evt.stop();
         }, { context: 'pre' });
+        this._initAriaAnnouncements();
+    }
+    /**
+     * Observe when user enters or leaves code block and set proper aria value in global live announcer.
+     * This allows screen readers to indicate when the user has entered and left the specified code block.
+     *
+     * @internal
+     */
+    _initAriaAnnouncements() {
+        const { model, ui, t } = this.editor;
+        const languageDefs = getNormalizedAndLocalizedLanguageDefinitions(this.editor);
+        let lastFocusedCodeBlock = null;
+        model.document.selection.on('change:range', () => {
+            const focusParent = model.document.selection.focus.parent;
+            if (!ui || lastFocusedCodeBlock === focusParent || !focusParent.is('element')) {
+                return;
+            }
+            if (lastFocusedCodeBlock && lastFocusedCodeBlock.is('element', 'codeBlock')) {
+                ui.ariaLiveAnnouncer.announce(getCodeBlockAriaAnnouncement(t, languageDefs, lastFocusedCodeBlock, 'leave'));
+            }
+            if (focusParent.is('element', 'codeBlock')) {
+                ui.ariaLiveAnnouncer.announce(getCodeBlockAriaAnnouncement(t, languageDefs, focusParent, 'enter'));
+            }
+            lastFocusedCodeBlock = focusParent;
+        });
     }
 }
 /**

package/src/utils.d.ts

@@ -8,6 +8,7 @@
 import type { Editor } from 'ckeditor5/src/core.js';
 import type { CodeBlockLanguageDefinition } from './codeblockconfig.js';
 import type { DocumentSelection, Element, Model, Position, Schema, Text, UpcastWriter, ViewDocumentFragment } from 'ckeditor5/src/engine.js';
+import { type LocaleTranslate } from 'ckeditor5/src/utils.js';
 /**
  * Returns code block languages as defined in `config.codeBlock.languages` but processed:
  *
@@ -136,3 +137,7 @@ export declare function isModelSelectionInCodeBlock(selection: DocumentSelection
  * @returns Check result.
  */
 export declare function canBeCodeBlock(schema: Schema, element: Element): boolean;
+/**
+ * Get the translated message read by the screen reader when you enter or exit an element with your cursor.
+ */
+export declare function getCodeBlockAriaAnnouncement(t: LocaleTranslate, languageDefs: Array<CodeBlockLanguageDefinition>, element: Element, direction: 'enter' | 'leave'): string;

package/src/utils.js

@@ -207,3 +207,21 @@ export function canBeCodeBlock(schema, element) {
     }
     return schema.checkChild(element.parent, 'codeBlock');
 }
+/**
+ * Get the translated message read by the screen reader when you enter or exit an element with your cursor.
+ */
+export function getCodeBlockAriaAnnouncement(t, languageDefs, element, direction) {
+    const languagesToLabels = getPropertyAssociation(languageDefs, 'language', 'label');
+    const codeBlockLanguage = element.getAttribute('language');
+    if (codeBlockLanguage in languagesToLabels) {
+        const language = languagesToLabels[codeBlockLanguage];
+        if (direction === 'enter') {
+            return t('Entering %0 code snippet', language);
+        }
+        return t('Leaving %0 code snippet', language);
+    }
+    if (direction === 'enter') {
+        return t('Entering code snippet');
+    }
+    return t('Leaving code snippet');
+}