Merge pull request #17278 from ckeditor/ck/epic/1944-bookmark

Feature (bookmark): Introduces the Bookmarks feature. Closes #1944. Fix (list): Inserting or dropping a paragraph after the end of a list should not convert the paragraph to a list item. Closes #17224.
ckeditor · Oct 24, 2024 · 21c6f46 · 21c6f46
2 parents 9decc1e + ea228d5
commit 21c6f46
Show file tree

Hide file tree

Showing 98 changed files with 11,603 additions and 73 deletions.
diff --git a/docs/_snippets/build-classic-source.js b/docs/_snippets/build-classic-source.js
@@ -6,9 +6,11 @@
 /* globals window */
 
 import { AutoImage, ImageInsert } from '@ckeditor/ckeditor5-image';
+import { Bookmark } from '@ckeditor/ckeditor5-bookmark';
 import ClassicEditor from './build-classic.js';
 
 window.ClassicEditor = ClassicEditor;
 
 ClassicEditor.builtinPlugins.push( ImageInsert );
 ClassicEditor.builtinPlugins.push( AutoImage );
+ClassicEditor.builtinPlugins.push( Bookmark );
diff --git a/docs/_snippets/examples/classic-editor.js b/docs/_snippets/examples/classic-editor.js
@@ -15,7 +15,7 @@ ClassicEditor
 				'undo', 'redo',
 				'|', 'heading',
 				'|', 'bold', 'italic',
-				'|', 'link', 'insertImage', 'insertTable', 'mediaEmbed',
+				'|', 'link', 'bookmark', 'insertImage', 'insertTable', 'mediaEmbed',
 				'|', 'bulletedList', 'numberedList', 'outdent', 'indent'
 			]
 		},

diff --git a/packages/ckeditor5-bookmark/CHANGELOG.md b/packages/ckeditor5-bookmark/CHANGELOG.md
@@ -0,0 +1,4 @@
+Changelog
+=========
+
+All changes in the package are documented in https://github.com/ckeditor/ckeditor5/blob/master/CHANGELOG.md.
diff --git a/packages/ckeditor5-bookmark/LICENSE.md b/packages/ckeditor5-bookmark/LICENSE.md
@@ -0,0 +1,17 @@
+Software License Agreement
+==========================
+
+**CKEditor&nbsp;5 bookmark feature** – https://github.com/ckeditor/packages/ckeditor5-bookmarks <br>
+Copyright (c) 2003–2024, [CKSource Holding sp. z o.o.](https://cksource.com) All rights reserved.
+
+Licensed under the terms of [GNU General Public License Version 2 or later](http://www.gnu.org/licenses/gpl.html).
+
+Sources of Intellectual Property Included in CKEditor
+-----------------------------------------------------
+
+Where not otherwise indicated, all CKEditor content is authored by CKSource engineers and consists of CKSource-owned intellectual property. In some specific instances, CKEditor will incorporate work done by developers outside of CKSource with their express permission.
+
+Trademarks
+----------
+
+**CKEditor** is a trademark of [CKSource Holding sp. z o.o.](https://cksource.com) All other brand and product names are trademarks, registered trademarks, or service marks of their respective holders.
diff --git a/packages/ckeditor5-bookmark/README.md b/packages/ckeditor5-bookmark/README.md
@@ -0,0 +1,26 @@
+CKEditor&nbsp;5 bookmark feature
+================================
+
+[![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-bookmark.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-bookmark)
+[![Coverage Status](https://coveralls.io/repos/github/ckeditor/ckeditor5/badge.svg?branch=master)](https://coveralls.io/github/ckeditor/ckeditor5?branch=master)
+[![Build Status](https://travis-ci.com/ckeditor/ckeditor5.svg?branch=master)](https://app.travis-ci.com/github/ckeditor/ckeditor5)
+
+This package contains the bookmark feature for CKEditor&nbsp;5. It allows to add and manage the bookmarks attached to the content of editor for fast access and more efficient content creation.
+
+## Demo
+
+Check out the [demo in the bookmark feature](https://ckeditor.com/docs/ckeditor5/latest/features/bookmarks.html#demo) guide.
+
+## Documentation
+
+See the [`@ckeditor/ckeditor5-bookmark` package](https://ckeditor.com/docs/ckeditor5/latest/api/bookmark.html) page in [CKEditor&nbsp;5 documentation](https://ckeditor.com/docs/ckeditor5/latest/) as well as the [bookmark](https://ckeditor.com/docs/ckeditor5/latest/features/bookmarks.html) feature guide.
+
+## Installation
+
+```bash
+npm install ckeditor5
+```
+
+## License
+
+Licensed under the terms of [GNU General Public License Version 2 or later](http://www.gnu.org/licenses/gpl.html). For full details about the license, please check the `LICENSE.md` file or [https://ckeditor.com/legal/ckeditor-oss-license](https://ckeditor.com/legal/ckeditor-oss-license).
diff --git a/packages/ckeditor5-bookmark/ckeditor5-metadata.json b/packages/ckeditor5-bookmark/ckeditor5-metadata.json
@@ -0,0 +1,24 @@
+{
+	"plugins": [
+		{
+			"name": "Bookmark",
+			"className": "Bookmark",
+			"description": "Allows to insert a bookmark into the content to provide fast access to important sections.",
+			"docs": "features/bookmarks.html",
+			"path": "src/bookmark.js",
+			"uiComponents": [
+				{
+					"type": "Button",
+					"name": "bookmark",
+					"iconPath": "@ckeditor/ckeditor5-core/theme/icons/bookmark.svg"
+				}
+			],
+			"htmlOutput": [
+				{
+					"elements": "a",
+					"attributes": "id"
+				}
+			]
+		}
+	]
+}
diff --git a/packages/ckeditor5-bookmark/docs/_snippets/features/bookmark.html b/packages/ckeditor5-bookmark/docs/_snippets/features/bookmark.html
@@ -0,0 +1,38 @@
+
+<div class="ck ck-content" id="snippet-bookmark">
+	<h2>
+		PUBLISHING AGREEMENT
+	</h2>
+	<h3>
+		Introduction
+	</h3>
+	<p>
+		This publishing contract, the “contract”, is entered into as of 1st June 2020 by and between The Lower Shelf, the “Publisher”, and John Smith, the “Author”.
+	</p>
+	<h3>
+		<a id="Rights"></a>Grant of Rights
+	</h3>
+	<p>
+		The Author grants the Publisher full right and title to the following, in perpetuity:
+	</p>
+	<ul>
+		<li>
+			To publish, sell, and profit from the listed works in all languages and formats in existence today and at any point in the future.
+		</li>
+		<li>
+			To create or devise modified, abridged, or derivative works based on the works listed.
+		</li>
+		<li>
+			To allow others to use the listed works at their discretion, without providing additional compensation to the Author.
+		</li>
+	</ul>
+	<p>
+		The Author grants these rights on behalf of him and their successors, heirs, executors, and any other party who may attempt to lay claim to these rights at any point now or in the future.
+	</p>
+	<p>
+		Any rights not granted to the Publisher above remain with the Author.
+	</p>
+	<p>
+		The rights granted to the Publisher by the Author shall not be constrained by geographic territories and are considered global in nature.
+	</p>
+</div>
diff --git a/packages/ckeditor5-bookmark/docs/_snippets/features/bookmark.js b/packages/ckeditor5-bookmark/docs/_snippets/features/bookmark.js
@@ -0,0 +1,69 @@
+/**
+ * @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
+ */
+
+/* globals console, window, document */
+
+// source editing only added for testing purposes, remove when done
+
+import { CKBox, CKBoxImageEdit } from '@ckeditor/ckeditor5-ckbox';
+import { PictureEditing, ImageInsert, ImageResize, AutoImage } from '@ckeditor/ckeditor5-image';
+import { LinkImage } from '@ckeditor/ckeditor5-link';
+import { Bookmark } from '@ckeditor/ckeditor5-bookmark';
+import { SourceEditing } from '@ckeditor/ckeditor5-source-editing';
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config.js';
+import { TOKEN_URL } from '@ckeditor/ckeditor5-ckbox/tests/_utils/ckbox-config.js';
+
+// Umberto combines all `packages/*/docs` into the `docs/` directory. The import path must be valid after merging all directories.
+import ClassicEditor from '../build-classic.js';
+
+ClassicEditor.builtinPlugins.push( Bookmark, PictureEditing, ImageInsert, SourceEditing,
+	ImageResize, AutoImage, LinkImage, CKBox, CKBoxImageEdit );
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-bookmark' ), {
+		toolbar: {
+			items: [
+				'bookmark',
+				'|', 'undo', 'redo', '|', 'heading',
+				'|', 'bold', 'italic',
+				'link', 'insertImage', 'insertTable', 'blockQuote', 'mediaEmbed',
+				'|', 'bulletedList', 'numberedList', 'outdent', 'indent', 'sourceEditing'
+			]
+		},
+		menuBar: {
+			isVisible: true
+		},
+		image: {
+			toolbar: [
+				'imageStyle:inline', 'imageStyle:block', 'imageStyle:wrapText', '|',
+				'toggleImageCaption', 'imageTextAlternative', 'ckboxImageEdit'
+			]
+		},
+		ui: {
+			viewportOffset: {
+				top: window.getViewportTopOffsetConfig()
+			}
+		},
+		ckbox: {
+			tokenUrl: TOKEN_URL,
+			allowExternalImagesEditing: [ /^data:/, 'origin', /ckbox/ ],
+			forceDemoLabel: true
+		},
+		cloudServices: CS_CONFIG
+	} )
+	.then( editor => {
+		window.editorBasic = editor;
+		window.attachTourBalloon( {
+			target: window.findToolbarItem( editor.ui.view.toolbar, item => item.label && item.label === 'Bookmark' ),
+			text: 'Click to insert a bookmark.',
+			editor,
+			tippyOptions: {
+				placement: 'bottom-start'
+			}
+		} );
+	} )
+	.catch( err => {
+		console.error( err );
+	} );
diff --git a/packages/ckeditor5-bookmark/docs/api/bookmark.md b/packages/ckeditor5-bookmark/docs/api/bookmark.md
@@ -0,0 +1,36 @@
+---
+category: api-reference
+---
+
+# CKEditor&nbsp;5 bookmark feature
+
+[![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-block-quote.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-bookmark)
+
+This package implements bookmark support for CKEditor&nbsp;5.
+
+## Demo
+
+Check out the {@link features/bookmarks#demo demo in the bookmarks feature guide}.
+
+## Documentation
+
+See the {@link features/bookmarks bookmarks feature guide} and the {@link module:block-quote/blockquote~BlockQuote} plugin documentation.
+
+## Installation
+
+This package is part of our open-source aggregate package.
+
+```bash
+npm install ckeditor5
+```
+
+## Contribute
+
+The source code of this package is available on GitHub in [https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-bookmark](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-bookmark).
+
+## External links
+
+* [`@ckeditor/ckeditor5-bookmark` on npm](https://www.npmjs.com/package/@ckeditor/ckeditor5-bookmark)
+* [`ckeditor/ckeditor5-bookmark` on GitHub](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-bookmark)
+* [Issue tracker](https://github.com/ckeditor/ckeditor5/issues)
+* [Changelog](https://github.com/ckeditor/ckeditor5/blob/master/CHANGELOG.md)
diff --git a/packages/ckeditor5-bookmark/docs/features/bookmarks.md b/packages/ckeditor5-bookmark/docs/features/bookmarks.md
@@ -0,0 +1,110 @@
+---
+category: features
+menu-title: Bookmarks
+meta-title: Bookmarks | CKEditor 5 Documentation
+meta-description: The bookmarks feature allows for adding and managing bookmark anchors attached to the content.
+modified_at: 2024-10-21
+---
+
+# Bookmarks
+
+The bookmarks feature allows for adding and managing the bookmarks anchors attached to the content of the editor. These provide fast access to important content sections, speed up the editing navigation and contribute to a more efficient content creation.
+
+## Demo
+
+Use the bookmark toolbar button {@icon @ckeditor/ckeditor5-core/theme/icons/bookmark.svg Add bookmark} in the editor below to see the feature in action. Or use the "Insert" command from the menu bar to add a bookmark. Add a unique name to identify the bookmark (for example, `Rights`).
+
+To use the bookmark as an anchor in the content, add a link {@icon @ckeditor/ckeditor5-link/theme/icons/link.svg Add link} and put the bookmark name as target. In this example it would be `#Rights`. You can change the bookmark's name or remove it by clicking the bookmark icon inside the content. A contextual bookmark toolbar will pop up.
+
+{@snippet features/bookmark}
+
+<info-box info>
+	This demo presents a limited set of features. Visit the {@link examples/builds/full-featured-editor feature-rich editor example} to see more in action.
+</info-box>
+
+## Handling the anchor markup
+
+Do not worry about setting a bookmark inside an empty paragraph. The block with the `a` tag will not be rendered in the final content (for example for printing).
+
+The feature converts anchors into bookmarks during the {@link getting-started/setup/getting-and-setting-data#initializing-the-editor-with-data initialization of the editor} or while {@link getting-started/setup/getting-and-setting-data#replacing-the-editor-data-with-setdata replacing the editor data with `setData()`}. The notation based on the `id` attribute in an `a` HTML element without a `href` attribute is converted. Similar notations meet the conditions, too:
+* an `a` HTML element with a `name` attribute,
+* an `a` HTML element with the same `name` and `id` attributes,
+* an `a` HTML element with different `name` and `id` attributes.
+
+By default, all bookmarks created in the editor only have the `id="..."` attribute in the {@link getting-started/setup/getting-and-setting-data#getting-the-editor-data-with-getdata editor data}.
+
+## Installation
+
+<info-box info>
+	⚠️ **New import paths**
+
+	Starting with {@link updating/update-to-42 version 42.0.0}, we changed the format of import paths. This guide uses the new, shorter format. Refer to the {@link getting-started/legacy-getting-started/legacy-imports Packages in the legacy setup} guide if you use an older version of CKEditor&nbsp;5.
+</info-box>
+
+After {@link getting-started/quick-start installing the editor}, add the feature to your plugin list and toolbar configuration:
+
+```js
+import { ClassicEditor, Bookmark } from 'ckeditor5';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ Bookmark, /* ... */ ],
+		toolbar: [ 'bookmark', /* ... */ ]
+	} )
+	.then( /* ... */ )
+	.catch( /* ... */ );
+```
+
+## Configuration
+
+By default, the conversion of wrapped anchors is turned on. It allows to convert non-empty anchor elements into bookmarks. For example:
+
+```html
+<a id="foo">Foo bar baz</a>
+```
+
+will be converted into a bookmark and the output will look like on the example below:
+
+```html
+<a id="foo"></a>Foo bar baz
+```
+
+You can disable the automatic conversion by setting the {@link module:bookmark/bookmarkconfig~BookmarkConfig#enableNonEmptyAnchorConversion `config.bookmark.enableNonEmptyAnchorConversion`} to `false` in the editor configuration.
+
+```js
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ Bookmark, /* ... */ ],
+		toolbar: [ 'bookmark', /* ... */ ],
+		bookmark: {
+			enableNonEmptyAnchorConversion: false
+		}
+	} )
+	.then( /* ... */ )
+	.catch( /* ... */ );
+```
+## Bookmarks on blocks
+
+At this time, if a bookmark is attached to a block, it appears before it. However, we plan to expand this solution in the future. We invite you to help us [gather feedback for linking directly to blocks and auto generating IDs](https://github.com/ckeditor/ckeditor5/issues/17264).
+
+## Related features
+
+Here are some other CKEditor&nbsp;5 features that you can use similarly to the bookmark plugin to cross-link and structure your text better:
+
+* The {@link features/link link feature} allows adding local and global URLs to the content.
+* The {@link features/document-outline document outline} displays the list of sections (headings) of the document next to the editor.
+* The {@link features/document-outline table of contents} lets you insert a widget with a list of headings (section titles) that reflects the structure of the document.
+
+## Common API
+
+The {@link module:bookmark/bookmark~Bookmark} plugin registers the `'bookmark'` UI button component implemented by the {@link module:bookmark/bookmarkui~BookmarkUI bookmark UI feature}, and the following commands:
+* the `'insertBookmark'` command implemented by the {@link module:bookmark/insertbookmarkcommand~InsertBookmarkCommand editing feature}.
+* the `'updateBookmark'` command implemented by the {@link module:bookmark/updatebookmarkcommand~UpdateBookmarkCommand editing feature}.
+
+<info-box>
+	We recommend using the official {@link framework/development-tools/inspector CKEditor&nbsp;5 inspector} for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.
+</info-box>
+
+## Contribute
+
+The source code of the feature is available on GitHub at [https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-bookmark](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-bookmark).
diff --git a/packages/ckeditor5-bookmark/lang/contexts.json b/packages/ckeditor5-bookmark/lang/contexts.json
@@ -0,0 +1,13 @@
+{
+	"Bookmark": "The label of the bookmark toolbar button. Also, a bookmark form header.",
+	"Insert": "The button in the bookmark insert form.",
+	"Update": "The button in the bookmark update form.",
+	"Edit bookmark": "Button opening the Bookmark editing balloon.",
+	"Remove bookmark": "Toolbar button tooltip for bookmark remove button.",
+	"Bookmark name": "The label of the input in the bookmark insert and update form. Also, the tooltip for the bookmark name in the bookmark preview.",
+	"Enter the bookmark name without spaces.": "The description of bookmark input in the bookmark insert form.",
+	"Bookmark must not be empty.": "The error message. Displayed when the bookmark name is empty.",
+	"Bookmark name cannot contain space characters.": "The error message. Displayed when provided name includes spaces.",
+	"Bookmark name already exists.": "The error message. Displayed when provided name already exists.",
+	"bookmark widget": "The label for the bookmark widget."
+}