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

package/src/insertbookmarkcommand.js

@@ -0,0 +1,113 @@
+/**
+ * @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 { logWarning } from 'ckeditor5/src/utils.js';
+import { Command } from 'ckeditor5/src/core.js';
+import { isBookmarkIdValid } from './utils.js';
+/**
+ * The insert bookmark command.
+ *
+ * The command is registered by {@link module:bookmark/bookmarkediting~BookmarkEditing} as `'insertBookmark'`.
+ *
+ * To insert a bookmark element at place where is the current collapsed selection or where is the beginning of document selection,
+ * execute the command passing the bookmark id as a parameter:
+ *
+ * ```ts
+ * editor.execute( 'insertBookmark', { bookmarkId: 'foo_bar' } );
+ * ```
+ */
+export default class InsertBookmarkCommand extends Command {
+    /**
+     * @inheritDoc
+     */
+    refresh() {
+        const model = this.editor.model;
+        const selection = model.document.selection;
+        const position = this._getPositionToInsertBookmark(selection);
+        this.isEnabled = !!position;
+    }
+    /**
+     * Executes the command.
+     *
+     * @fires execute
+     * @param options Command options.
+     * @param options.bookmarkId The value of the `bookmarkId` attribute.
+     */
+    execute(options) {
+        if (!options) {
+            return;
+        }
+        const { bookmarkId } = options;
+        if (!isBookmarkIdValid(bookmarkId)) {
+            /**
+             * Insert bookmark command can be executed only with a valid name.
+             *
+             * A valid bookmark name must be a non-empty string and must not contain any spaces.
+             *
+             * @error insert-bookmark-command-executed-with-invalid-name
+             */
+            logWarning('insert-bookmark-command-executed-with-invalid-name');
+            return;
+        }
+        const editor = this.editor;
+        const model = editor.model;
+        const selection = model.document.selection;
+        model.change(writer => {
+            let position = this._getPositionToInsertBookmark(selection);
+            const isBookmarkAllowed = model.schema.checkChild(position, 'bookmark');
+            // If the position does not allow for `bookmark` but allows for a `paragraph`
+            // then insert a `paragraph` then we will insert a `bookmark` inside.
+            if (!isBookmarkAllowed) {
+                const newPosition = editor.execute('insertParagraph', { position });
+                if (!newPosition) {
+                    return;
+                }
+                position = newPosition;
+            }
+            const bookmarkElement = writer.createElement('bookmark', {
+                ...Object.fromEntries(selection.getAttributes()),
+                bookmarkId
+            });
+            model.insertObject(bookmarkElement, position, null, { setSelection: 'on' });
+        });
+    }
+    /**
+     * Returns the position where the bookmark can be inserted. And if it is not possible to insert a bookmark,
+     * check if it is possible to insert a paragraph.
+     */
+    _getPositionToInsertBookmark(selection) {
+        const model = this.editor.model;
+        const schema = model.schema;
+        const firstRange = selection.getFirstRange();
+        const startPosition = firstRange.start;
+        // Return position if it is allowed to insert bookmark or if it is allowed to insert paragraph.
+        if (isBookmarkAllowed(startPosition, schema)) {
+            return startPosition;
+        }
+        for (const { previousPosition, item } of firstRange) {
+            // When the table cell is selected (from the outside) we look for the first paragraph-like element inside.
+            if (item.is('element') &&
+                schema.checkChild(item, '$text') &&
+                isBookmarkAllowed(item, schema)) {
+                return model.createPositionAt(item, 0);
+            }
+            if (isBookmarkAllowed(previousPosition, schema)) {
+                return previousPosition;
+            }
+        }
+        return null;
+    }
+}
+/**
+ * Verify if the given position allows for bookmark insertion. Verify if auto-paragraphing could help.
+ */
+function isBookmarkAllowed(position, schema) {
+    if (schema.checkChild(position, 'bookmark')) {
+        return true;
+    }
+    if (!schema.checkChild(position, 'paragraph')) {
+        return false;
+    }
+    return schema.checkChild('paragraph', 'bookmark');
+}

package/src/ui/bookmarkactionsview.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @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/ui/bookmarkactionsview
+ */
+import { LabelView, ButtonView, View } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler, type LocaleTranslate, type Locale } from 'ckeditor5/src/utils.js';
+import '@ckeditor/ckeditor5-ui/theme/components/responsive-form/responsiveform.css';
+import '../../theme/bookmarkactions.css';
+/**
+ * The bookmark actions view class. This view displays the bookmark preview, allows
+ * removing or editing the bookmark.
+ */
+export default class BookmarkActionsView extends View {
+    /**
+     * Tracks information about DOM focus in the actions.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * The bookmark preview view.
+     */
+    bookmarkPreviewView: LabelView;
+    /**
+     * The remove button view.
+     */
+    removeButtonView: ButtonView;
+    /**
+     * The edit bookmark button view.
+     */
+    editButtonView: ButtonView;
+    /**
+     * The id preview view.
+     *
+     * @observable
+     */
+    id: string | undefined;
+    /**
+     * A collection of views that can be focused in the view.
+     */
+    private readonly _focusables;
+    /**
+     * Helps cycling over {@link #_focusables} in the view.
+     */
+    private readonly _focusCycler;
+    t: LocaleTranslate;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the fist {@link #_focusables} in the actions.
+     */
+    focus(): void;
+    /**
+     * Creates a button view.
+     *
+     * @param label The button label.
+     * @param icon The button icon.
+     * @param eventName An event name that the `ButtonView#execute` event will be delegated to.
+     * @param additionalLabel An additional label outside the button.
+     * @returns The button view instance.
+     */
+    private _createButton;
+    /**
+     * Creates a bookmark name preview label.
+     *
+     * @returns The label view instance.
+     */
+    private _createBookmarkPreviewView;
+}
+/**
+ * Fired when the {@link ~BookmarkActionsView#editButtonView} is clicked.
+ *
+ * @eventName ~BookmarkActionsView#edit
+ */
+export type EditEvent = {
+    name: 'edit';
+    args: [];
+};
+/**
+ * Fired when the {@link ~BookmarkActionsView#removeButtonView} is clicked.
+ *
+ * @eventName ~BookmarkActionsView#remove
+ */
+export type RemoveEvent = {
+    name: 'remove';
+    args: [];
+};

package/src/ui/bookmarkactionsview.js

@@ -0,0 +1,154 @@
+/**
+ * @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/ui/bookmarkactionsview
+ */
+import { LabelView, ButtonView, View, ViewCollection, FocusCycler } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler } from 'ckeditor5/src/utils.js';
+import { icons } from 'ckeditor5/src/core.js';
+// eslint-disable-next-line ckeditor5-rules/ckeditor-imports
+import '@ckeditor/ckeditor5-ui/theme/components/responsive-form/responsiveform.css';
+import '../../theme/bookmarkactions.css';
+/**
+ * The bookmark actions view class. This view displays the bookmark preview, allows
+ * removing or editing the bookmark.
+ */
+export default class BookmarkActionsView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale) {
+        super(locale);
+        /**
+         * Tracks information about DOM focus in the actions.
+         */
+        this.focusTracker = new FocusTracker();
+        /**
+         * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+         */
+        this.keystrokes = new KeystrokeHandler();
+        /**
+         * A collection of views that can be focused in the view.
+         */
+        this._focusables = new ViewCollection();
+        const t = locale.t;
+        this.bookmarkPreviewView = this._createBookmarkPreviewView();
+        this.removeButtonView = this._createButton(t('Remove bookmark'), icons.remove, 'remove', this.bookmarkPreviewView);
+        this.editButtonView = this._createButton(t('Edit bookmark'), icons.pencil, 'edit', this.bookmarkPreviewView);
+        this.set('id', undefined);
+        this._focusCycler = new FocusCycler({
+            focusables: this._focusables,
+            focusTracker: this.focusTracker,
+            keystrokeHandler: this.keystrokes,
+            actions: {
+                // Navigate fields backwards using the Shift + Tab keystroke.
+                focusPrevious: 'shift + tab',
+                // Navigate fields forwards using the Tab key.
+                focusNext: 'tab'
+            }
+        });
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-bookmark-actions',
+                    'ck-responsive-form'
+                ],
+                // https://github.com/ckeditor/ckeditor5-link/issues/90
+                tabindex: '-1'
+            },
+            children: [
+                this.bookmarkPreviewView,
+                this.editButtonView,
+                this.removeButtonView
+            ]
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        const childViews = [
+            this.editButtonView,
+            this.removeButtonView
+        ];
+        childViews.forEach(v => {
+            // Register the view as focusable.
+            this._focusables.add(v);
+            // Register the view in the focus tracker.
+            this.focusTracker.add(v.element);
+        });
+        // Start listening for the keystrokes coming from #element.
+        this.keystrokes.listenTo(this.element);
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        this.focusTracker.destroy();
+        this.keystrokes.destroy();
+    }
+    /**
+     * Focuses the fist {@link #_focusables} in the actions.
+     */
+    focus() {
+        this._focusCycler.focusFirst();
+    }
+    /**
+     * Creates a button view.
+     *
+     * @param label The button label.
+     * @param icon The button icon.
+     * @param eventName An event name that the `ButtonView#execute` event will be delegated to.
+     * @param additionalLabel An additional label outside the button.
+     * @returns The button view instance.
+     */
+    _createButton(label, icon, eventName, additionalLabel) {
+        const button = new ButtonView(this.locale);
+        button.set({
+            label,
+            icon,
+            tooltip: true
+        });
+        button.delegate('execute').to(this, eventName);
+        // Since button label `id` is bound to the `ariaLabelledBy` property
+        // we need to modify this binding to include only the first ID token
+        // as this button will be labeled by multiple labels.
+        button.labelView.unbind('id');
+        button.labelView.bind('id').to(button, 'ariaLabelledBy', ariaLabelledBy => {
+            return getFirstToken(ariaLabelledBy);
+        });
+        button.ariaLabelledBy = `${button.ariaLabelledBy} ${additionalLabel.id}`;
+        return button;
+    }
+    /**
+     * Creates a bookmark name preview label.
+     *
+     * @returns The label view instance.
+     */
+    _createBookmarkPreviewView() {
+        const label = new LabelView(this.locale);
+        label.extendTemplate({
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-bookmark-actions__preview'
+                ]
+            }
+        });
+        // Bind label text with the bookmark ID.
+        label.bind('text').to(this, 'id');
+        return label;
+    }
+}
+/**
+ * Returns the first token from space separated token list.
+ */
+function getFirstToken(tokenList) {
+    return tokenList.split(' ')[0];
+}

package/src/ui/bookmarkformview.d.ts

@@ -0,0 +1,118 @@
+/**
+ * @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/ui/bookmarkformview
+ */
+import { ButtonView, LabeledFieldView, View, ViewCollection, type InputTextView } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler, type Locale } from 'ckeditor5/src/utils.js';
+import '@ckeditor/ckeditor5-ui/theme/components/responsive-form/responsiveform.css';
+import '../../theme/bookmarkform.css';
+/**
+ * The bookmark form view controller class.
+ *
+ * See {@link module:bookmark/ui/bookmarkformview~BookmarkFormView}.
+ */
+export default class BookmarkFormView extends View {
+    /**
+     * Tracks information about DOM focus in the form.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * The ID input view.
+     */
+    idInputView: LabeledFieldView<InputTextView>;
+    /**
+     * The Submit button view.
+     */
+    buttonView: ButtonView;
+    /**
+     * A collection of form child views in the form.
+     */
+    readonly children: ViewCollection;
+    /**
+     * An array of form validators used by {@link #isValid}.
+     */
+    private readonly _validators;
+    /**
+     * A collection of views that can be focused in the form.
+     */
+    private readonly _focusables;
+    /**
+     * Helps cycling over {@link #_focusables} in the form.
+     */
+    private readonly _focusCycler;
+    /**
+     * Creates an instance of the {@link module:bookmark/ui/bookmarkformview~BookmarkFormView} class.
+     *
+     * Also see {@link #render}.
+     *
+     * @param locale The localization services instance.
+     * @param validators  Form validators used by {@link #isValid}.
+     */
+    constructor(locale: Locale, validators: Array<BookmarkFormValidatorCallback>);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the fist {@link #_focusables} in the form.
+     */
+    focus(): void;
+    /**
+     * Validates the form and returns `false` when some fields are invalid.
+     */
+    isValid(): boolean;
+    /**
+     * Cleans up the supplementary error and information text of the {@link #idInputView}
+     * bringing them back to the state when the form has been displayed for the first time.
+     *
+     * See {@link #isValid}.
+     */
+    resetFormStatus(): void;
+    /**
+     * Creates header and form view.
+     */
+    private _createViewChildren;
+    /**
+     * Creates form content view with input and button.
+     */
+    private _createFormContentView;
+    /**
+     * Creates a labeled input view.
+     *
+     * @returns Labeled field view instance.
+     */
+    private _createIdInput;
+    /**
+     * Creates a button view.
+     *
+     * @param label The button label.
+     * @param className The additional button CSS class name.
+     * @returns The button view instance.
+     */
+    private _createButton;
+    /**
+     * The native DOM `value` of the {@link #idInputView} element.
+     *
+     * **Note**: Do not confuse it with the {@link module:ui/inputtext/inputtextview~InputTextView#value}
+     * which works one way only and may not represent the actual state of the component in the DOM.
+     */
+    get id(): string | null;
+}
+/**
+ * Callback used by {@link ~BookmarkFormView} to check if passed form value is valid.
+ *
+ * If `undefined` is returned, it is assumed that the form value is correct and there is no error.
+ * If string is returned, it is assumed that the form value is incorrect and the returned string is displayed in the error label
+ */
+export type BookmarkFormValidatorCallback = (form: BookmarkFormView) => string | undefined;

package/src/ui/bookmarkformview.js

@@ -0,0 +1,203 @@
+/**
+ * @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/ui/bookmarkformview
+ */
+import { ButtonView, FocusCycler, LabeledFieldView, View, ViewCollection, createLabeledInputText, submitHandler, FormHeaderView } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler } from 'ckeditor5/src/utils.js';
+// See: #8833.
+// eslint-disable-next-line ckeditor5-rules/ckeditor-imports
+import '@ckeditor/ckeditor5-ui/theme/components/responsive-form/responsiveform.css';
+import '../../theme/bookmarkform.css';
+/**
+ * The bookmark form view controller class.
+ *
+ * See {@link module:bookmark/ui/bookmarkformview~BookmarkFormView}.
+ */
+export default class BookmarkFormView extends View {
+    /**
+     * Creates an instance of the {@link module:bookmark/ui/bookmarkformview~BookmarkFormView} class.
+     *
+     * Also see {@link #render}.
+     *
+     * @param locale The localization services instance.
+     * @param validators  Form validators used by {@link #isValid}.
+     */
+    constructor(locale, validators) {
+        super(locale);
+        /**
+         * Tracks information about DOM focus in the form.
+         */
+        this.focusTracker = new FocusTracker();
+        /**
+         * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+         */
+        this.keystrokes = new KeystrokeHandler();
+        /**
+         * A collection of views that can be focused in the form.
+         */
+        this._focusables = new ViewCollection();
+        const t = locale.t;
+        this._validators = validators;
+        this.idInputView = this._createIdInput();
+        this.buttonView = this._createButton(t('Insert'), 'ck-button-action ck-button-bold');
+        this.buttonView.type = 'submit';
+        this.children = this._createViewChildren();
+        this._focusCycler = new FocusCycler({
+            focusables: this._focusables,
+            focusTracker: this.focusTracker,
+            keystrokeHandler: this.keystrokes,
+            actions: {
+                // Navigate form fields backwards using the Shift + Tab keystroke.
+                focusPrevious: 'shift + tab',
+                // Navigate form fields forwards using the Tab key.
+                focusNext: 'tab'
+            }
+        });
+        const classList = ['ck', 'ck-bookmark-view'];
+        this.setTemplate({
+            tag: 'form',
+            attributes: {
+                class: classList,
+                // https://github.com/ckeditor/ckeditor5-link/issues/90
+                tabindex: '-1'
+            },
+            children: this.children
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        submitHandler({
+            view: this
+        });
+        const childViews = [
+            this.idInputView,
+            this.buttonView
+        ];
+        childViews.forEach(v => {
+            // Register the view as focusable.
+            this._focusables.add(v);
+            // Register the view in the focus tracker.
+            this.focusTracker.add(v.element);
+        });
+        // Start listening for the keystrokes coming from #element.
+        this.keystrokes.listenTo(this.element);
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        this.focusTracker.destroy();
+        this.keystrokes.destroy();
+    }
+    /**
+     * Focuses the fist {@link #_focusables} in the form.
+     */
+    focus() {
+        this._focusCycler.focusFirst();
+    }
+    /**
+     * Validates the form and returns `false` when some fields are invalid.
+     */
+    isValid() {
+        this.resetFormStatus();
+        for (const validator of this._validators) {
+            const errorText = validator(this);
+            // One error per field is enough.
+            if (errorText) {
+                // Apply updated error.
+                this.idInputView.errorText = errorText;
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Cleans up the supplementary error and information text of the {@link #idInputView}
+     * bringing them back to the state when the form has been displayed for the first time.
+     *
+     * See {@link #isValid}.
+     */
+    resetFormStatus() {
+        this.idInputView.errorText = null;
+    }
+    /**
+     * Creates header and form view.
+     */
+    _createViewChildren() {
+        const children = this.createCollection();
+        const t = this.t;
+        children.add(new FormHeaderView(this.locale, { label: t('Bookmark') }));
+        children.add(this._createFormContentView());
+        return children;
+    }
+    /**
+     * Creates form content view with input and button.
+     */
+    _createFormContentView() {
+        const view = new View(this.locale);
+        const children = this.createCollection();
+        const classList = ['ck', 'ck-bookmark-form', 'ck-responsive-form'];
+        children.add(this.idInputView);
+        children.add(this.buttonView);
+        view.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: classList
+            },
+            children
+        });
+        return view;
+    }
+    /**
+     * Creates a labeled input view.
+     *
+     * @returns Labeled field view instance.
+     */
+    _createIdInput() {
+        const t = this.locale.t;
+        const labeledInput = new LabeledFieldView(this.locale, createLabeledInputText);
+        labeledInput.label = t('Bookmark name');
+        labeledInput.infoText = t('Enter the bookmark name without spaces.');
+        return labeledInput;
+    }
+    /**
+     * Creates a button view.
+     *
+     * @param label The button label.
+     * @param className The additional button CSS class name.
+     * @returns The button view instance.
+     */
+    _createButton(label, className) {
+        const button = new ButtonView(this.locale);
+        button.set({
+            label,
+            withText: true
+        });
+        button.extendTemplate({
+            attributes: {
+                class: className
+            }
+        });
+        return button;
+    }
+    /**
+     * The native DOM `value` of the {@link #idInputView} element.
+     *
+     * **Note**: Do not confuse it with the {@link module:ui/inputtext/inputtextview~InputTextView#value}
+     * which works one way only and may not represent the actual state of the component in the DOM.
+     */
+    get id() {
+        const { element } = this.idInputView.fieldView;
+        if (!element) {
+            return null;
+        }
+        return element.value.trim();
+    }
+}