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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-highlight",
-  "version": "36.0.1",
+  "version": "37.0.0-alpha.0",
   "description": "Highlight feature for CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -12,22 +12,22 @@
   ],
   "main": "src/index.js",
   "dependencies": {
-    "ckeditor5": "^36.0.1"
+    "ckeditor5": "^37.0.0-alpha.0"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-block-quote": "^36.0.1",
-    "@ckeditor/ckeditor5-core": "^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-heading": "^36.0.1",
-    "@ckeditor/ckeditor5-image": "^36.0.1",
-    "@ckeditor/ckeditor5-list": "^36.0.1",
-    "@ckeditor/ckeditor5-paragraph": "^36.0.1",
-    "@ckeditor/ckeditor5-theme-lark": "^36.0.1",
-    "@ckeditor/ckeditor5-typing": "^36.0.1",
-    "@ckeditor/ckeditor5-utils": "^36.0.1",
+    "@ckeditor/ckeditor5-block-quote": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-core": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-dev-utils": "^34.0.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-image": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-list": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-paragraph": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-theme-lark": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-typing": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-utils": "^37.0.0-alpha.0",
     "typescript": "^4.8.4",
     "webpack": "^5.58.1",
     "webpack-cli": "^4.9.0"
@@ -58,5 +58,6 @@
     "dll:build": "webpack",
     "build": "tsc -p ./tsconfig.release.json",
     "postversion": "npm run build"
-  }
+  },
+  "types": "src/index.d.ts"
 }

package/src/highlight.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @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 highlight/highlight
+ */
+import { Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+/**
+ * The highlight plugin.
+ *
+ * For a detailed overview, check the {@glink features/highlight Highlight feature} documentation.
+ *
+ * This is a "glue" plugin which loads the {@link module:highlight/highlightediting~HighlightEditing} and
+ * {@link module:highlight/highlightui~HighlightUI} plugins.
+ */
+export default class Highlight extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'Highlight';
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [Highlight.pluginName]: Highlight;
+    }
+}

package/src/highlightcommand.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @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 highlight/highlightcommand
+ */
+import { Command } from 'ckeditor5/src/core';
+/**
+ * The highlight command. It is used by the {@link module:highlight/highlightediting~HighlightEditing highlight feature}
+ * to apply the text highlighting.
+ *
+ * ```ts
+ * editor.execute( 'highlight', { value: 'greenMarker' } );
+ * ```
+ *
+ * **Note**: Executing the command without a value removes the attribute from the model. If the selection is collapsed
+ * inside a text with the highlight attribute, the command will remove the attribute from the entire range
+ * of that text.
+ */
+export default class HighlightCommand extends Command {
+    /**
+     * A value indicating whether the command is active. If the selection has some highlight attribute,
+     * it corresponds to the value of that attribute.
+     *
+     * @observable
+     * @readonly
+     */
+    value: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command.
+     *
+     * @param options Options for the executed command.
+     * @param options.value The value to apply.
+     *
+     * @fires execute
+     */
+    execute(options?: {
+        value?: string | null;
+    }): void;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface CommandsMap {
+        highlight: HighlightCommand;
+    }
+}

package/src/highlightconfig.d.ts

@@ -0,0 +1,181 @@
+/**
+ * @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 highlight/highlightconfig
+ */
+/**
+ * The highlight option descriptor. See {@link module:highlight/highlightconfig~HighlightConfig} to learn more.
+ *
+ * ```ts
+ * {
+ * 	model: 'pinkMarker',
+ * 	class: 'marker-pink',
+ * 	title: 'Pink Marker',
+ * 	color: 'var(--ck-highlight-marker-pink)',
+ * 	type: 'marker'
+ * }
+ * ```
+ */
+export interface HighlightOption {
+    /**
+     * The user-readable title of the option.
+     */
+    title: string;
+    /**
+     * The unique attribute value in the model.
+     */
+    model: string;
+    /**
+     * The CSS `var()` used for the highlighter. The color is used in the user interface to represent the highlighter.
+     * There is a possibility to use the default color format like rgb, hex or hsl, but you need to care about the color of `<mark>`
+     * by adding CSS classes definition.
+     */
+    color: string;
+    /**
+     * The CSS class used on the `<mark>` element in the view. It should match the `color` setting.
+     */
+    class: string;
+    /**
+     * The type of highlighter:
+     *
+     * * `'marker'` &ndash; Uses the `color` as the `background-color` style,
+     * * `'pen'` &ndash; Uses the `color` as the font `color` style.
+     */
+    type: 'marker' | 'pen';
+}
+/**
+ * The configuration of the {@link module:highlight/highlight~Highlight highlight feature}.
+ * ```ts
+ * ClassicEditor
+ * 	.create( editorElement, {
+ * 		highlight:  ... // Highlight feature configuration.
+ * 	} )
+ * 	.then( ... )
+ * 	.catch( ... );
+ * ```
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ */
+export interface HighlightConfig {
+    /**
+     * The available highlight options. The default value is:
+     * ```ts
+     * options: [
+     * 	{
+     * 		model: 'yellowMarker',
+     * 		class: 'marker-yellow',
+     * 		title: 'Yellow marker',
+     * 		color: 'var(--ck-highlight-marker-yellow)',
+     * 		type: 'marker'
+     * 	},
+     * 	{
+     * 		model: 'greenMarker',
+     * 		class: 'marker-green',
+     * 		title: 'Green marker',
+     * 		color: 'var(--ck-highlight-marker-green)',
+     * 		type: 'marker'
+     * 	},
+     * 	{
+     * 		model: 'pinkMarker',
+     * 		class: 'marker-pink',
+     * 		title: 'Pink marker',
+     * 		color: 'var(--ck-highlight-marker-pink)',
+     * 		type: 'marker'
+     * 	},
+     * 	{
+     * 		model: 'blueMarker',
+     * 		class: 'marker-blue',
+     * 		title: 'Blue marker',
+     * 		color: 'var(--ck-highlight-marker-blue)',
+     * 		type: 'marker'
+     * 	},
+     * 	{
+     * 		model: 'redPen',
+     * 		class: 'pen-red',
+     * 		title: 'Red pen',
+     * 		color: 'var(--ck-highlight-pen-red)',
+     * 		type: 'pen'
+     * 	},
+     * 	{
+     * 		model: 'greenPen',
+     * 		class: 'pen-green',
+     * 		title: 'Green pen',
+     * 		color: 'var(--ck-highlight-pen-green)',
+     * 		type: 'pen'
+     * 	}
+     * ]
+     * ```
+     *
+     * There are two types of highlighters available:
+     *
+     * * `'marker'` &ndash; Rendered as a `<mark>` element, styled with the `background-color`.
+     * * `'pen'` &ndash; Rendered as a `<mark>` element, styled with the font `color`.
+     *
+     * **Note**: The highlight feature provides a stylesheet with the CSS classes and corresponding colors defined
+     * as CSS variables.
+     *
+     * ```css
+     * :root {
+     * 	--ck-highlight-marker-yellow: #fdfd77;
+     * 	--ck-highlight-marker-green: #63f963;
+     * 	--ck-highlight-marker-pink: #fc7999;
+     * 	--ck-highlight-marker-blue: #72cdfd;
+     * 	--ck-highlight-pen-red: #e91313;
+     * 	--ck-highlight-pen-green: #118800;
+     * }
+     *
+     * .marker-yellow { ... }
+     * .marker-green { ... }
+     * .marker-pink { ... }
+     * .marker-blue { ... }
+     * .pen-red { ... }
+     * .pen-green { ... }
+     * ```
+     *
+     * It is possible to define the `color` property directly as `rgba(R, G, B, A)`,
+     * `#RRGGBB[AA]` or `hsla(H, S, L, A)`. In such situation, the color will **only** apply to the UI of
+     * the editor and the `<mark>` elements in the content must be styled by custom classes provided by
+     * a dedicated stylesheet.
+     *
+     * **Note**: It is recommended for the `color` property to correspond to the class in the content
+     * stylesheet because it represents the highlighter in the user interface of the editor.
+     *
+     * ```ts
+     * ClassicEditor
+     * 	.create( editorElement, {
+     * 		highlight: {
+     * 			options: [
+     * 				{
+     * 					model: 'pinkMarker',
+     * 					class: 'marker-pink',
+     * 					title: 'Pink Marker',
+     * 					color: 'var(--ck-highlight-marker-pink)',
+     * 					type: 'marker'
+     * 				},
+     * 				{
+     * 					model: 'redPen',
+     * 					class: 'pen-red',
+     * 					title: 'Red Pen',
+     * 					color: 'var(--ck-highlight-pen-red)',
+     * 					type: 'pen'
+     * 				},
+     * 			]
+     * 		}
+     * } )
+     * .then( ... )
+     * .catch( ... );
+     * ```
+     */
+    options: Array<HighlightOption>;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface EditorConfig {
+        /**
+         * The configuration of the {@link module:highlight/highlight~Highlight} feature.
+         *
+         * Read more in {@link module:highlight/highlightconfig~HighlightConfig}.
+         */
+        highlight?: HighlightConfig;
+    }
+}

package/src/highlightconfig.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/highlightediting.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 highlight/highlightediting
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core';
+/**
+ * The highlight editing feature. It introduces the {@link module:highlight/highlightcommand~HighlightCommand command} and the `highlight`
+ * attribute in the {@link module:engine/model/model~Model model} which renders in the {@link module:engine/view/view view}
+ * as a `<mark>` element with a `class` attribute (`<mark class="marker-green">...</mark>`) depending
+ * on the {@link module:highlight/highlightconfig~HighlightConfig configuration}.
+ */
+export default class HighlightEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'HighlightEditing';
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [HighlightEditing.pluginName]: HighlightEditing;
+    }
+}

package/src/highlightediting.js

@@ -11,7 +11,7 @@ import HighlightCommand from './highlightcommand';
  * The highlight editing feature. It introduces the {@link module:highlight/highlightcommand~HighlightCommand command} and the `highlight`
  * attribute in the {@link module:engine/model/model~Model model} which renders in the {@link module:engine/view/view view}
  * as a `<mark>` element with a `class` attribute (`<mark class="marker-green">...</mark>`) depending
- * on the {@link module:highlight/highlight~HighlightConfig configuration}.
+ * on the {@link module:highlight/highlightconfig~HighlightConfig configuration}.
  */
 export default class HighlightEditing extends Plugin {
     /**

package/src/highlightui.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @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 highlight/highlightui
+ */
+import { Plugin } from 'ckeditor5/src/core';
+import './../theme/highlight.css';
+/**
+ * The default highlight UI plugin. It introduces:
+ *
+ * * The `'highlight'` dropdown,
+ * * The `'removeHighlight'` and `'highlight:*'` buttons.
+ *
+ * The default configuration includes the following buttons:
+ *
+ * * `'highlight:yellowMarker'`
+ * * `'highlight:greenMarker'`
+ * * `'highlight:pinkMarker'`
+ * * `'highlight:blueMarker'`
+ * * `'highlight:redPen'`
+ * * `'highlight:greenPen'`
+ *
+ * See the {@link module:highlight/highlightconfig~HighlightConfig#options configuration} to learn more
+ * about the defaults.
+ */
+export default class HighlightUI extends Plugin {
+    /**
+     * Returns the localized option titles provided by the plugin.
+     *
+     * The following localized titles corresponding with default
+     * {@link module:highlight/highlightconfig~HighlightConfig#options} are available:
+     *
+     * * `'Yellow marker'`,
+     * * `'Green marker'`,
+     * * `'Pink marker'`,
+     * * `'Blue marker'`,
+     * * `'Red pen'`,
+     * * `'Green pen'`.
+     */
+    get localizedOptionTitles(): Record<string, string>;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'HighlightUI';
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Creates the "Remove highlight" button.
+     */
+    private _addRemoveHighlightButton;
+    /**
+     * Creates a toolbar button from the provided highlight option.
+     */
+    private _addHighlighterButton;
+    /**
+     * Internal method for creating highlight buttons.
+     *
+     * @param name The name of the button.
+     * @param label The label for the button.
+     * @param icon The button icon.
+     * @param value The `value` property passed to the executed command.
+     * @param decorateButton A callback getting ButtonView instance so that it can be further customized.
+     */
+    private _addButton;
+    /**
+     * Creates the split button dropdown UI from the provided highlight options.
+     */
+    private _addDropdown;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [HighlightUI.pluginName]: HighlightUI;
+    }
+}

package/src/highlightui.js

@@ -25,7 +25,7 @@ import './../theme/highlight.css';
  * * `'highlight:redPen'`
  * * `'highlight:greenPen'`
  *
- * See the {@link module:highlight/highlight~HighlightConfig#options configuration} to learn more
+ * See the {@link module:highlight/highlightconfig~HighlightConfig#options configuration} to learn more
  * about the defaults.
  */
 export default class HighlightUI extends Plugin {
@@ -33,7 +33,7 @@ export default class HighlightUI extends Plugin {
      * Returns the localized option titles provided by the plugin.
      *
      * The following localized titles corresponding with default
-     * {@link module:highlight/highlight~HighlightConfig#options} are available:
+     * {@link module:highlight/highlightconfig~HighlightConfig#options} are available:
      *
      * * `'Yellow marker'`,
      * * `'Green marker'`,

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 highlight
+ */
+export { default as Highlight } from './highlight';
+export { default as HighlightEditing } from './highlightediting';
+export { default as HighlightUI } from './highlightui';