@ckeditor/ckeditor5-heading 36.0.1 → 37.0.0-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-heading",
-  "version": "36.0.1",
+  "version": "37.0.0-alpha.1",
   "description": "Headings feature for CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -12,26 +12,26 @@
   ],
   "main": "src/index.js",
   "dependencies": {
-    "ckeditor5": "^36.0.1"
+    "ckeditor5": "^37.0.0-alpha.1"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-alignment": "^36.0.1",
-    "@ckeditor/ckeditor5-basic-styles": "^36.0.1",
-    "@ckeditor/ckeditor5-block-quote": "^36.0.1",
-    "@ckeditor/ckeditor5-core": "^36.0.1",
-    "@ckeditor/ckeditor5-clipboard": "^36.0.1",
-    "@ckeditor/ckeditor5-dev-utils": "^32.0.0",
-    "@ckeditor/ckeditor5-editor-classic": "^36.0.1",
-    "@ckeditor/ckeditor5-engine": "^36.0.1",
-    "@ckeditor/ckeditor5-enter": "^36.0.1",
-    "@ckeditor/ckeditor5-image": "^36.0.1",
-    "@ckeditor/ckeditor5-paragraph": "^36.0.1",
-    "@ckeditor/ckeditor5-theme-lark": "^36.0.1",
-    "@ckeditor/ckeditor5-typing": "^36.0.1",
-    "@ckeditor/ckeditor5-ui": "^36.0.1",
-    "@ckeditor/ckeditor5-undo": "^36.0.1",
-    "@ckeditor/ckeditor5-upload": "^36.0.1",
-    "@ckeditor/ckeditor5-utils": "^36.0.1",
+    "@ckeditor/ckeditor5-alignment": "^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-core": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-clipboard": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-dev-utils": "^35.0.0",
+    "@ckeditor/ckeditor5-editor-classic": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-engine": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-enter": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-image": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-paragraph": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-theme-lark": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-typing": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-ui": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-undo": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-upload": "^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"
@@ -60,7 +60,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,30 @@
+/**
+ * @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 { Heading, HeadingCommand, HeadingConfig, HeadingEditing, HeadingUI, Title, TitleConfig } from './index';
+declare module '@ckeditor/ckeditor5-core' {
+    interface EditorConfig {
+        /**
+         * The configuration of the heading feature. Introduced by the {@link module:heading/headingediting~HeadingEditing} feature.
+         *
+         * Read more in {@link module:heading/headingconfig~HeadingConfig}.
+         */
+        heading?: HeadingConfig;
+        /**
+         * The configuration of the {@link module:heading/title~Title title feature}.
+         *
+         * Read more in {@link module:heading/title~TitleConfig}.
+         */
+        title?: TitleConfig;
+    }
+    interface PluginsMap {
+        [Heading.pluginName]: Heading;
+        [HeadingEditing.pluginName]: HeadingEditing;
+        [HeadingUI.pluginName]: HeadingUI;
+        [Title.pluginName]: Title;
+    }
+    interface CommandsMap {
+        heading: HeadingCommand;
+    }
+}

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/heading.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @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 heading/heading
+ */
+import { Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+import '../theme/heading.css';
+/**
+ * The headings feature.
+ *
+ * For a detailed overview, check the {@glink features/headings Headings feature} guide
+ * and the {@glink api/heading package page}.
+ *
+ * This is a "glue" plugin which loads the {@link module:heading/headingediting~HeadingEditing heading editing feature}
+ * and {@link module:heading/headingui~HeadingUI heading UI feature}.
+ *
+ * @extends module:core/plugin~Plugin
+ */
+export default class Heading extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'Heading';
+}

package/src/heading.js

@@ -12,7 +12,7 @@ import '../theme/heading.css';
 /**
  * The headings feature.
  *
- * For a detailed overview, check the {@glink features/headings Headings feature documentation}
+ * For a detailed overview, check the {@glink features/headings Headings feature} guide
  * and the {@glink api/heading package page}.
  *
  * This is a "glue" plugin which loads the {@link module:heading/headingediting~HeadingEditing heading editing feature}

package/src/headingbuttonsui.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @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 heading/headingbuttonsui
+ */
+import { Plugin } from 'ckeditor5/src/core';
+/**
+ * The `HeadingButtonsUI` plugin defines a set of UI buttons that can be used instead of the
+ * standard drop down component.
+ *
+ * This feature is not enabled by default by the {@link module:heading/heading~Heading} plugin and needs to be
+ * installed manually to the editor configuration.
+ *
+ * Plugin introduces button UI elements, which names are same as `model` property from {@link module:heading/headingconfig~HeadingOption}.
+ *
+ * ```ts
+ * ClassicEditor
+ *   .create( {
+ *     plugins: [ ..., Heading, Paragraph, HeadingButtonsUI, ParagraphButtonUI ]
+ *     heading: {
+ *       options: [
+ *         { model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
+ *         { model: 'heading1', view: 'h2', title: 'Heading 1', class: 'ck-heading_heading1' },
+ *         { model: 'heading2', view: 'h3', title: 'Heading 2', class: 'ck-heading_heading2' },
+ *         { model: 'heading3', view: 'h4', title: 'Heading 3', class: 'ck-heading_heading3' }
+ *       ]
+ *      },
+ *      toolbar: [ 'paragraph', 'heading1', 'heading2', 'heading3' ]
+ *   } )
+ *   .then( ... )
+ *   .catch( ... );
+ * ```
+ *
+ * NOTE: The `'paragraph'` button is defined in by the {@link module:paragraph/paragraphbuttonui~ParagraphButtonUI} plugin
+ * which needs to be loaded manually as well.
+ *
+ * It is possible to use custom icons by providing `icon` config option in {@link module:heading/headingconfig~HeadingOption}.
+ * For the default configuration standard icons are used.
+ */
+export default class HeadingButtonsUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Creates single button view from provided configuration option.
+     */
+    private _createButton;
+}

package/src/headingbuttonsui.js

@@ -29,7 +29,7 @@ const defaultIcons = {
  * This feature is not enabled by default by the {@link module:heading/heading~Heading} plugin and needs to be
  * installed manually to the editor configuration.
  *
- * Plugin introduces button UI elements, which names are same as `model` property from {@link module:heading/heading~HeadingOption}.
+ * Plugin introduces button UI elements, which names are same as `model` property from {@link module:heading/headingconfig~HeadingOption}.
  *
  * ```ts
  * ClassicEditor
@@ -52,7 +52,7 @@ const defaultIcons = {
  * NOTE: The `'paragraph'` button is defined in by the {@link module:paragraph/paragraphbuttonui~ParagraphButtonUI} plugin
  * which needs to be loaded manually as well.
  *
- * It is possible to use custom icons by providing `icon` config option in {@link module:heading/heading~HeadingOption}.
+ * It is possible to use custom icons by providing `icon` config option in {@link module:heading/headingconfig~HeadingOption}.
  * For the default configuration standard icons are used.
  */
 export default class HeadingButtonsUI extends Plugin {

package/src/headingcommand.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @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 heading/headingcommand
+ */
+import { Command, type Editor } from 'ckeditor5/src/core';
+/**
+ * The heading command. It is used by the {@link module:heading/heading~Heading heading feature} to apply headings.
+ */
+export default class HeadingCommand extends Command {
+    /**
+     * If the selection starts in a heading (which {@link #modelElements is supported by this command})
+     * the value is set to the name of that heading model element.
+     * It is  set to `false` otherwise.
+     *
+     * @observable
+     * @readonly
+     */
+    value: false | string;
+    /**
+     * Set of defined model's elements names that this command support.
+     * See {@link module:heading/headingconfig~HeadingOption}.
+     */
+    readonly modelElements: Array<string>;
+    /**
+     * Creates an instance of the command.
+     *
+     * @param editor Editor instance.
+     * @param modelElements Names of the element which this command can apply in the model.
+     */
+    constructor(editor: Editor, modelElements: Array<string>);
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command. Applies the heading to the selected blocks or, if the first selected
+     * block is a heading already, turns selected headings (of this level only) to paragraphs.
+     *
+     * @param options.value Name of the element which this command will apply in the model.
+     * @fires execute
+     */
+    execute(options: {
+        value: string;
+    }): void;
+}

package/src/headingconfig.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @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 heading/headingconfig
+ */
+import type { ViewElementDefinition } from 'ckeditor5/src/engine';
+/**
+ * The configuration of the heading feature.
+ * The option is used by the {@link module:heading/headingediting~HeadingEditing} feature.
+ *
+ * ```ts
+ * ClassicEditor
+ *   .create( {
+ *     heading: ... // Heading feature config.
+ *   } )
+ *   .then( ... )
+ *   .catch( ... );
+ * ```
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ */
+export interface HeadingConfig {
+    /**
+     * The available heading options.
+     *
+     * The default value is:
+     * ```ts
+     * const headingConfig = {
+     *   options: [
+     *     { model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
+     *     { model: 'heading1', view: 'h2', title: 'Heading 1', class: 'ck-heading_heading1' },
+     *     { model: 'heading2', view: 'h3', title: 'Heading 2', class: 'ck-heading_heading2' },
+     *     { model: 'heading3', view: 'h4', title: 'Heading 3', class: 'ck-heading_heading3' }
+     *   ]
+     * };
+     * ```
+     *
+     * It defines 3 levels of headings. In the editor model they will use `heading1`, `heading2`, and `heading3` elements.
+     * Their respective view elements (so the elements output by the editor) will be: `h2`, `h3`, and `h4`. This means that
+     * if you choose "Heading 1" in the headings dropdown the editor will turn the current block to `<heading1>` in the model
+     * which will result in rendering (and outputting to data) the `<h2>` element.
+     *
+     * The `title` and `class` properties will be used by the `headings` dropdown to render available options.
+     * Usually, the first option in the headings dropdown is the "Paragraph" option, hence it's also defined on the list.
+     * However, you don't need to define its view representation because it's handled by
+     * the {@link module:paragraph/paragraph~Paragraph} feature (which is required by
+     * the {@link module:heading/headingediting~HeadingEditing} feature).
+     *
+     * You can **read more** about configuring heading levels and **see more examples** in
+     * the {@glink features/headings Headings} guide.
+     *
+     * Note: In the model you should always start from `heading1`, regardless of how the headings are represented in the view.
+     * That's assumption is used by features like {@link module:autoformat/autoformat~Autoformat} to know which element
+     * they should use when applying the first level heading.
+     *
+     * The defined headings are also available as values passed to the `'heading'` command under their model names.
+     * For example, the below code will apply `<heading1>` to the current selection:
+     *
+     * ```ts
+     * editor.execute( 'heading', { value: 'heading1' } );
+     * ```
+     */
+    options?: Array<HeadingOption>;
+}
+/**
+ * Heading option descriptor.
+ */
+export type HeadingOption = HeadingElementOption | HeadingParagraphOption;
+export interface HeadingElementOption {
+    /**
+     * Name of the model element to convert.
+     */
+    model: 'heading1' | 'heading2' | 'heading3' | 'heading4' | 'heading5' | 'heading6';
+    /**
+     * Definition of a view element to convert from/to.
+     */
+    view: ViewElementDefinition;
+    /**
+     * The user-readable title of the option.
+     */
+    title: string;
+    /**
+     * The class which will be added to the dropdown item representing this option.
+     */
+    class: string;
+    /**
+     * Icon used by {@link module:heading/headingbuttonsui~HeadingButtonsUI}. It can be omitted when using the default configuration.
+     */
+    icon?: string;
+}
+export interface HeadingParagraphOption {
+    /**
+     * Name of the model element to convert.
+     */
+    model: 'paragraph';
+    /**
+     * The user-readable title of the option.
+     */
+    title: string;
+    /**
+     * The class which will be added to the dropdown item representing this option.
+     * */
+    class: string;
+    /**
+     * Icon used by {@link module:heading/headingbuttonsui~HeadingButtonsUI}. It can be omitted when using the default configuration.
+     */
+    icon?: string;
+}

package/src/headingconfig.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/headingediting.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @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 heading/headingediting
+ */
+import { Plugin, type Editor, type PluginDependencies } from 'ckeditor5/src/core';
+/**
+ * The headings engine feature. It handles switching between block formats – headings and paragraph.
+ * This class represents the engine part of the heading feature. See also {@link module:heading/heading~Heading}.
+ * It introduces `heading1`-`headingN` commands which allow to convert paragraphs into headings.
+ */
+export default class HeadingEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'HeadingEditing';
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    afterInit(): void;
+    /**
+     * Adds default conversion for `h1` -> `heading1` with a low priority.
+     *
+     * @param editor Editor instance on which to add the `h1` conversion.
+     */
+    private _addDefaultH1Conversion;
+}

package/src/headingui.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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 heading/headingui
+ */
+import { Plugin } from 'ckeditor5/src/core';
+import '../theme/heading.css';
+/**
+ * The headings UI feature. It introduces the `headings` dropdown.
+ */
+export default class HeadingUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'HeadingUI';
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/src/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @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 heading
+ */
+export { default as Heading } from './heading';
+export type { HeadingOption } from './headingconfig';
+export { default as HeadingEditing } from './headingediting';
+export { default as HeadingUI } from './headingui';
+export { default as HeadingButtonsUI } from './headingbuttonsui';
+export { default as Title, type TitleConfig } from './title';
+export type { HeadingConfig } from './headingconfig';
+export type { default as HeadingCommand } from './headingcommand';
+import './augmentation';

package/src/index.js

@@ -10,3 +10,4 @@ export { default as HeadingEditing } from './headingediting';
 export { default as HeadingUI } from './headingui';
 export { default as HeadingButtonsUI } from './headingbuttonsui';
 export { default as Title } from './title';
+import './augmentation';

package/src/title.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @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 heading/title
+ */
+import { Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+/**
+ * The Title plugin.
+ *
+ * It splits the document into `Title` and `Body` sections.
+ */
+export default class Title extends Plugin {
+    /**
+     * A reference to an empty paragraph in the body
+     * created when there is no element in the body for the placeholder purposes.
+     */
+    private _bodyPlaceholder?;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'Title';
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Returns the title of the document. Note that because this plugin does not allow any formatting inside
+     * the title element, the output of this method will be a plain text, with no HTML tags.
+     *
+     * It is not recommended to use this method together with features that insert markers to the
+     * data output, like comments or track changes features. If such markers start in the title and end in the
+     * body, the result of this method might be incorrect.
+     *
+     * @param options Additional configuration passed to the conversion process.
+     * See {@link module:engine/controller/datacontroller~DataController#get `DataController#get`}.
+     * @returns The title of the document.
+     */
+    getTitle(options?: Record<string, unknown>): string;
+    /**
+     * Returns the body of the document.
+     *
+     * Note that it is not recommended to use this method together with features that insert markers to the
+     * data output, like comments or track changes features. If such markers start in the title and end in the
+     * body, the result of this method might be incorrect.
+     *
+     * @param options Additional configuration passed to the conversion process.
+     * See {@link module:engine/controller/datacontroller~DataController#get `DataController#get`}.
+     * @returns The body of the document.
+     */
+    getBody(options?: Record<string, unknown>): string;
+    /**
+     * Returns the `title` element when it is in the document. Returns `undefined` otherwise.
+     */
+    private _getTitleElement;
+    /**
+     * Model post-fixer callback that ensures that `title` has only one `title-content` child.
+     * All additional children should be moved after the `title` element and renamed to a paragraph.
+     */
+    private _fixTitleContent;
+    /**
+     * Model post-fixer callback that creates a title element when it is missing,
+     * takes care of the correct position of it and removes additional title elements.
+     */
+    private _fixTitleElement;
+    /**
+     * Model post-fixer callback that adds an empty paragraph at the end of the document
+     * when it is needed for the placeholder purposes.
+     */
+    private _fixBodyElement;
+    /**
+     * Model post-fixer callback that removes a paragraph from the end of the document
+     * if it was created for the placeholder purposes and is not needed anymore.
+     */
+    private _fixExtraParagraph;
+    /**
+     * Attaches the `Title` and `Body` placeholders to the title and/or content.
+     */
+    private _attachPlaceholders;
+    /**
+     * Creates navigation between the title and body sections using <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys.
+     */
+    private _attachTabPressHandling;
+}
+/**
+ * The configuration of the {@link module:heading/title~Title title feature}.
+ *
+ * ```ts
+ * ClassicEditor
+ *   .create( document.querySelector( '#editor' ), {
+ *     plugins: [ Title, ... ],
+ *     title: {
+ *       placeholder: 'My custom placeholder for the title'
+ *     },
+ *     placeholder: 'My custom placeholder for the body'
+ *   } )
+ *   .then( ... )
+ *   .catch( ... );
+ * ```
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor configuration options}.
+ */
+export interface TitleConfig {
+    /**
+     * Defines a custom value of the placeholder for the title field.
+     *
+     * Read more in {@link module:heading/title~TitleConfig}.
+     */
+    placeholder?: string;
+}

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 heading/utils
+ */
+import type { Editor } from 'ckeditor5/src/core';
+import type { HeadingOption } from './headingconfig';
+/**
+ * Returns heading options as defined in `config.heading.options` but processed to consider
+ * the editor localization, i.e. to display {@link module:heading/headingconfig~HeadingOption}
+ * in the correct language.
+ *
+ * Note: The reason behind this method is that 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.
+ */
+export declare function getLocalizedOptions(editor: Editor): Array<HeadingOption>;

package/src/utils.js

@@ -4,7 +4,7 @@
  */
 /**
  * Returns heading options as defined in `config.heading.options` but processed to consider
- * the editor localization, i.e. to display {@link module:heading/heading~HeadingOption}
+ * the editor localization, i.e. to display {@link module:heading/headingconfig~HeadingOption}
  * in the correct language.
  *
  * Note: The reason behind this method is that there is no way to use {@link module:utils/locale~Locale#t}