@ckeditor/ckeditor5-bookmark 0.0.1 → 44.0.0-alpha.0

package/src/bookmarkediting.js

@@ -0,0 +1,211 @@
+/**
+ * @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 bookmark/bookmarkediting
+ */
+import { Plugin, icons } from 'ckeditor5/src/core.js';
+import { toWidget } from 'ckeditor5/src/widget.js';
+import { IconView } from 'ckeditor5/src/ui.js';
+import InsertBookmarkCommand from './insertbookmarkcommand.js';
+import UpdateBookmarkCommand from './updatebookmarkcommand.js';
+import '../theme/bookmark.css';
+/**
+ * The bookmark editing plugin.
+ */
+export default class BookmarkEditing extends Plugin {
+    constructor() {
+        super(...arguments);
+        /**
+         * A collection of bookmarks elements in the document.
+         */
+        this._bookmarkElements = new Map();
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'BookmarkEditing';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const { editor } = this;
+        this._defineSchema();
+        this._defineConverters();
+        editor.commands.add('insertBookmark', new InsertBookmarkCommand(editor));
+        editor.commands.add('updateBookmark', new UpdateBookmarkCommand(editor));
+        this.listenTo(editor.model.document, 'change:data', () => {
+            this._trackBookmarkElements();
+        });
+    }
+    /**
+     * Returns the model element for the given bookmark ID if it exists.
+     */
+    getElementForBookmarkId(bookmarkId) {
+        for (const [element, id] of this._bookmarkElements) {
+            if (id == bookmarkId) {
+                return element;
+            }
+        }
+        return null;
+    }
+    /**
+     * Defines the schema for the bookmark feature.
+     */
+    _defineSchema() {
+        const schema = this.editor.model.schema;
+        schema.register('bookmark', {
+            inheritAllFrom: '$inlineObject',
+            allowAttributes: 'bookmarkId',
+            disallowAttributes: ['linkHref', 'htmlA']
+        });
+    }
+    /**
+     * Defines the converters for the bookmark feature.
+     */
+    _defineConverters() {
+        const { editor } = this;
+        const { conversion, t } = editor;
+        editor.data.htmlProcessor.domConverter.registerInlineObjectMatcher(element => upcastMatcher(element));
+        // Register an inline object matcher so that bookmarks <a>s are correctly recognized as inline elements in editing pipeline.
+        // This prevents converting spaces around bookmarks to `&nbsp;`s.
+        editor.editing.view.domConverter.registerInlineObjectMatcher(element => upcastMatcher(element, false));
+        conversion.for('dataDowncast').elementToElement({
+            model: {
+                name: 'bookmark',
+                attributes: ['bookmarkId']
+            },
+            view: (modelElement, { writer }) => {
+                const emptyElement = writer.createEmptyElement('a', {
+                    'id': modelElement.getAttribute('bookmarkId')
+                });
+                // `getFillerOffset` is not needed to set here, because `emptyElement` has already covered it.
+                return emptyElement;
+            }
+        });
+        conversion.for('editingDowncast').elementToElement({
+            model: {
+                name: 'bookmark',
+                attributes: ['bookmarkId']
+            },
+            view: (modelElement, { writer }) => {
+                const id = modelElement.getAttribute('bookmarkId');
+                const containerElement = writer.createContainerElement('a', {
+                    id,
+                    class: 'ck-bookmark'
+                }, [this._createBookmarkUIElement(writer)]);
+                this._bookmarkElements.set(modelElement, id);
+                // `getFillerOffset` is not needed to set here, because `toWidget` has already covered it.
+                const labelCreator = () => `${id} ${t('bookmark widget')}`;
+                return toWidget(containerElement, writer, { label: labelCreator });
+            }
+        });
+        conversion.for('upcast').add(dispatcher => dispatcher.on('element:a', dataViewModelAnchorInsertion(editor)));
+    }
+    /**
+     * Creates a UI element for the `bookmark` representation in editing view.
+     */
+    _createBookmarkUIElement(writer) {
+        return writer.createUIElement('span', { class: 'ck-bookmark__icon' }, function (domDocument) {
+            const domElement = this.toDomElement(domDocument);
+            const icon = new IconView();
+            icon.set({
+                content: icons.bookmarkInline,
+                isColorInherited: false
+            });
+            icon.render();
+            domElement.appendChild(icon.element);
+            return domElement;
+        });
+    }
+    /**
+     * Tracking the added or removed bookmark elements.
+     */
+    _trackBookmarkElements() {
+        this._bookmarkElements.forEach((id, element) => {
+            if (element.root.rootName === '$graveyard') {
+                this._bookmarkElements.delete(element);
+            }
+        });
+    }
+}
+/**
+ * A helper function to match an `anchor` element which must contain `id` or `name` attribute but without `href` attribute,
+ * also when `expectEmpty` is set to `true` but the element is not empty matcher should not match any element.
+ *
+ * @param element The element to be checked.
+ * @param expectEmpty Default set to `true`, when set to `false` matcher expects that `anchor` is not empty;
+ * in editing pipeline it's not empty because it contains the `UIElement`.
+ */
+function upcastMatcher(element, expectEmpty = true) {
+    const isAnchorElement = element.name === 'a';
+    if (!isAnchorElement) {
+        return null;
+    }
+    if (expectEmpty && !element.isEmpty) {
+        return null;
+    }
+    const hasIdAttribute = element.hasAttribute('id');
+    const hasNameAttribute = element.hasAttribute('name');
+    const hasHrefAttribute = element.hasAttribute('href');
+    if (hasIdAttribute && !hasHrefAttribute) {
+        return { name: true, attributes: ['id'] };
+    }
+    if (hasNameAttribute && !hasHrefAttribute) {
+        return { name: true, attributes: ['name'] };
+    }
+    return null;
+}
+/**
+ * A view-to-model converter that handles converting pointed or wrapped anchors with `id` and/or `name` attributes.
+ *
+ * @returns Returns a conversion callback.
+ */
+function dataViewModelAnchorInsertion(editor) {
+    return (evt, data, conversionApi) => {
+        const viewItem = data.viewItem;
+        const match = upcastMatcher(viewItem, false);
+        if (!match || !conversionApi.consumable.test(viewItem, match)) {
+            return;
+        }
+        const enableNonEmptyAnchorConversion = isEnabledNonEmptyAnchorConversion(editor);
+        if (!enableNonEmptyAnchorConversion && !viewItem.isEmpty) {
+            return;
+        }
+        const modelWriter = conversionApi.writer;
+        const anchorId = viewItem.getAttribute('id');
+        const anchorName = viewItem.getAttribute('name');
+        const bookmarkId = anchorId || anchorName;
+        const bookmark = modelWriter.createElement('bookmark', { bookmarkId });
+        if (!conversionApi.safeInsert(bookmark, data.modelCursor)) {
+            return;
+        }
+        conversionApi.consumable.consume(viewItem, match);
+        if (anchorId === anchorName) {
+            conversionApi.consumable.consume(viewItem, { attributes: ['name'] });
+        }
+        conversionApi.updateConversionResult(bookmark, data);
+        // Convert children uses the result of `bookmark` insertion to convert the `anchor` content
+        // after the bookmark element (not inside it).
+        const { modelCursor, modelRange } = conversionApi.convertChildren(viewItem, data.modelCursor);
+        data.modelCursor = modelCursor;
+        data.modelRange = modelWriter.createRange(data.modelRange.start, modelRange.end);
+    };
+}
+/**
+ * Normalize the bookmark configuration option `enableNonEmptyAnchorConversion`.
+ */
+function isEnabledNonEmptyAnchorConversion(editor) {
+    const enableNonEmptyAnchorConversion = editor.config.get('bookmark.enableNonEmptyAnchorConversion');
+    // When not defined, option `enableNonEmptyAnchorConversion` by default is set to `true`.
+    return enableNonEmptyAnchorConversion !== undefined ? enableNonEmptyAnchorConversion : true;
+}

package/src/bookmarkui.d.ts

@@ -0,0 +1,166 @@
+/**
+ * @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 bookmark/bookmarkui
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import { ContextualBalloon, type ViewWithCssTransitionDisabler } from 'ckeditor5/src/ui.js';
+import BookmarkFormView from './ui/bookmarkformview.js';
+import BookmarkActionsView from './ui/bookmarkactionsview.js';
+import BookmarkEditing from './bookmarkediting.js';
+/**
+ * The UI plugin of the bookmark feature.
+ *
+ * It registers the `'bookmark'` UI button in the editor's {@link module:ui/componentfactory~ComponentFactory component factory}
+ * which inserts the `bookmark` element upon selection.
+ */
+export default class BookmarkUI extends Plugin {
+    /**
+     * The actions view displayed inside of the balloon.
+     */
+    actionsView: BookmarkActionsView | null;
+    /**
+     * The form view displayed inside the balloon.
+     */
+    formView: BookmarkFormView & ViewWithCssTransitionDisabler | null;
+    /**
+     * The contextual balloon plugin instance.
+     */
+    private _balloon;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof BookmarkEditing, typeof ContextualBalloon];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "BookmarkUI";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Creates views.
+     */
+    private _createViews;
+    /**
+     * Creates the {@link module:bookmark/ui/bookmarkactionsview~BookmarkActionsView} instance.
+     */
+    private _createActionsView;
+    /**
+     * Creates the {@link module:bookmark/ui/bookmarkformview~BookmarkFormView} instance.
+     */
+    private _createFormView;
+    /**
+     * Creates a toolbar Bookmark button. Clicking this button will show
+     * a {@link #_balloon} attached to the selection.
+     */
+    private _createToolbarBookmarkButton;
+    /**
+     * Creates a button for `bookmark` command to use either in toolbar or in menu bar.
+     */
+    private _createButton;
+    /**
+     * Attaches actions that control whether the balloon panel containing the
+     * {@link #formView} should be displayed.
+     */
+    private _enableBalloonActivators;
+    /**
+     * Attaches actions that control whether the balloon panel containing the
+     * {@link #formView} is visible or not.
+     */
+    private _enableUserBalloonInteractions;
+    /**
+     * Updates the button label. If bookmark is selected label is set to 'Update' otherwise
+     * it is 'Insert'.
+     */
+    private _updateFormButtonLabel;
+    /**
+     * Adds the {@link #actionsView} to the {@link #_balloon}.
+     *
+     * @internal
+     */
+    _addActionsView(): void;
+    /**
+     * Adds the {@link #formView} to the {@link #_balloon}.
+     */
+    private _addFormView;
+    /**
+     * Closes the form view. Decides whether the balloon should be hidden completely.
+     */
+    private _closeFormView;
+    /**
+     * Removes the {@link #formView} from the {@link #_balloon}.
+     */
+    private _removeFormView;
+    /**
+     * Shows the correct UI type. It is either {@link #formView} or {@link #actionsView}.
+     */
+    private _showUI;
+    /**
+     * Removes the {@link #formView} from the {@link #_balloon}.
+     *
+     * See {@link #_addFormView}, {@link #_addActionsView}.
+     */
+    private _hideUI;
+    /**
+     * Makes the UI react to the {@link module:ui/editorui/editorui~EditorUI#event:update} event to
+     * reposition itself when the editor UI should be refreshed.
+     *
+     * See: {@link #_hideUI} to learn when the UI stops reacting to the `update` event.
+     */
+    private _startUpdatingUI;
+    /**
+     * Returns `true` when {@link #formView} is in the {@link #_balloon}.
+     */
+    private get _isFormInPanel();
+    /**
+     * Returns `true` when {@link #actionsView} is in the {@link #_balloon}.
+     */
+    private get _areActionsInPanel();
+    /**
+     * Returns `true` when {@link #actionsView} is in the {@link #_balloon} and it is
+     * currently visible.
+     */
+    private get _areActionsVisible();
+    /**
+     * Returns `true` when {@link #actionsView} or {@link #formView} is in the {@link #_balloon}.
+     */
+    private get _isUIInPanel();
+    /**
+     * Returns `true` when {@link #actionsView} or {@link #formView} is in the {@link #_balloon} and it is
+     * currently visible.
+     */
+    private get _isUIVisible();
+    /**
+     * Returns positioning options for the {@link #_balloon}. They control the way the balloon is attached
+     * to the target element or selection.
+     */
+    private _getBalloonPositionData;
+    /**
+     * Returns the bookmark {@link module:engine/view/attributeelement~AttributeElement} under
+     * the {@link module:engine/view/document~Document editing view's} selection or `null`
+     * if there is none.
+     */
+    private _getSelectedBookmarkElement;
+    /**
+     * Displays a fake visual selection when the contextual balloon is displayed.
+     *
+     * This adds a 'bookmark-ui' marker into the document that is rendered as a highlight on selected text fragment.
+     */
+    private _showFakeVisualSelection;
+    /**
+     * Hides the fake visual selection created in {@link #_showFakeVisualSelection}.
+     */
+    private _hideFakeVisualSelection;
+}