@ckeditor/ckeditor5-ui 41.1.0 → 41.2.0

package/src/editorui/accessibilityhelp/accessibilityhelp.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @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 ui/editorui/accessibilityhelp/accessibilityhelp
+ */
+import { Plugin } from '@ckeditor/ckeditor5-core';
+import { Dialog } from '../../index.js';
+import AccessibilityHelpContentView from './accessibilityhelpcontentview.js';
+import '../../../theme/components/editorui/accessibilityhelp.css';
+/**
+ * A plugin that brings the accessibility help dialog to the editor available under the <kbd>Alt</kbd>+<kbd>0</kbd>
+ * keystroke and via the "Accessibility help" toolbar button. The dialog displays a list of keystrokes that can be used
+ * by the user to perform various actions in the editor.
+ *
+ * Keystroke information is loaded from {@link module:core/accessibility~Accessibility#keystrokeInfos}. New entries can be
+ * added using the API provided by the {@link module:core/accessibility~Accessibility} class.
+ */
+export default class AccessibilityHelp extends Plugin {
+    /**
+     * The view that displays the dialog content (list of keystrokes).
+     * Created when the dialog is opened for the first time.
+     */
+    contentView: AccessibilityHelpContentView | null;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof Dialog];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "AccessibilityHelp";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Injects a help text into each editing root's `aria-label` attribute allowing assistive technology users
+     * to discover the availability of the Accessibility help dialog.
+     */
+    private _setupRootLabels;
+    /**
+     * Shows the accessibility help dialog. Also, creates {@link #contentView} on demand.
+     */
+    private _showDialog;
+}

package/src/editorui/accessibilityhelp/accessibilityhelp.js

@@ -0,0 +1,111 @@
+/**
+ * @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 ui/editorui/accessibilityhelp/accessibilityhelp
+ */
+import { Plugin } from '@ckeditor/ckeditor5-core';
+import { ButtonView, Dialog } from '../../index.js';
+import AccessibilityHelpContentView from './accessibilityhelpcontentview.js';
+import { getEnvKeystrokeText } from '@ckeditor/ckeditor5-utils';
+import accessibilityIcon from '../../../theme/icons/accessibility.svg';
+import '../../../theme/components/editorui/accessibilityhelp.css';
+/**
+ * A plugin that brings the accessibility help dialog to the editor available under the <kbd>Alt</kbd>+<kbd>0</kbd>
+ * keystroke and via the "Accessibility help" toolbar button. The dialog displays a list of keystrokes that can be used
+ * by the user to perform various actions in the editor.
+ *
+ * Keystroke information is loaded from {@link module:core/accessibility~Accessibility#keystrokeInfos}. New entries can be
+ * added using the API provided by the {@link module:core/accessibility~Accessibility} class.
+ */
+export default class AccessibilityHelp extends Plugin {
+    constructor() {
+        super(...arguments);
+        /**
+         * The view that displays the dialog content (list of keystrokes).
+         * Created when the dialog is opened for the first time.
+         */
+        this.contentView = null;
+    }
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [Dialog];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'AccessibilityHelp';
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        const t = editor.locale.t;
+        editor.ui.componentFactory.add('accessibilityHelp', locale => {
+            const buttonView = new ButtonView(locale);
+            buttonView.set({
+                label: t('Accessibility help'),
+                tooltip: true,
+                withText: false,
+                keystroke: 'Alt+0',
+                icon: accessibilityIcon
+            });
+            buttonView.on('execute', () => this._showDialog());
+            return buttonView;
+        });
+        editor.keystrokes.set('Alt+0', (evt, cancel) => {
+            this._showDialog();
+            cancel();
+        });
+        this._setupRootLabels();
+    }
+    /**
+     * Injects a help text into each editing root's `aria-label` attribute allowing assistive technology users
+     * to discover the availability of the Accessibility help dialog.
+     */
+    _setupRootLabels() {
+        const editor = this.editor;
+        const editingView = editor.editing.view;
+        const t = editor.t;
+        editor.ui.on('ready', () => {
+            editingView.change(writer => {
+                for (const root of editingView.document.roots) {
+                    addAriaLabelTextToRoot(writer, root);
+                }
+            });
+            editor.on('addRoot', (evt, modelRoot) => {
+                const viewRoot = editor.editing.view.document.getRoot(modelRoot.rootName);
+                editingView.change(writer => addAriaLabelTextToRoot(writer, viewRoot));
+            }, { priority: 'low' });
+        });
+        function addAriaLabelTextToRoot(writer, viewRoot) {
+            const currentAriaLabel = viewRoot.getAttribute('aria-label');
+            const newAriaLabel = `${currentAriaLabel}. ${t('Press %0 for help.', [getEnvKeystrokeText('Alt+0')])}`;
+            writer.setAttribute('aria-label', newAriaLabel, viewRoot);
+        }
+    }
+    /**
+     * Shows the accessibility help dialog. Also, creates {@link #contentView} on demand.
+     */
+    _showDialog() {
+        const editor = this.editor;
+        const dialog = editor.plugins.get('Dialog');
+        const t = editor.locale.t;
+        if (!this.contentView) {
+            this.contentView = new AccessibilityHelpContentView(editor.locale, editor.accessibility.keystrokeInfos);
+        }
+        dialog.show({
+            id: 'accessibilityHelp',
+            className: 'ck-accessibility-help-dialog',
+            title: t('Accessibility help'),
+            icon: accessibilityIcon,
+            hasCloseButton: true,
+            content: this.contentView
+        });
+    }
+}

package/src/editorui/accessibilityhelp/accessibilityhelpcontentview.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @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 ui/editorui/accessibilityhelp/accessibilityhelpcontentview
+ */
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+import View from '../../view.js';
+import type { KeystrokeInfoDefinitions } from '@ckeditor/ckeditor5-core';
+/**
+ * The view displaying keystrokes in the Accessibility help dialog.
+ */
+export default class AccessibilityHelpContentView extends View<HTMLDivElement> {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale, keystrokes: KeystrokeInfoDefinitions);
+    /**
+     * @inheritDoc
+     */
+    focus(): void;
+    /**
+     * Creates `<section><h3>Category label</h3>...</section>` elements for each category of keystrokes.
+     */
+    private _createCategories;
+    /**
+     * Creates `[<h4>Optional label</h4>]<dl>...</dl>` elements for each group of keystrokes in a category.
+     */
+    private _createGroup;
+    /**
+     * Creates `<dt>Keystroke label</dt><dd>Keystroke definition</dd>` elements for each keystroke in a group.
+     */
+    private _createGroupRow;
+}

package/src/editorui/accessibilityhelp/accessibilityhelpcontentview.js

@@ -0,0 +1,112 @@
+/**
+ * @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 ui/editorui/accessibilityhelp/accessibilityhelpcontentview
+ */
+import { createElement, env, getEnvKeystrokeText } from '@ckeditor/ckeditor5-utils';
+import View from '../../view.js';
+import LabelView from '../../label/labelview.js';
+/**
+ * The view displaying keystrokes in the Accessibility help dialog.
+ */
+export default class AccessibilityHelpContentView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale, keystrokes) {
+        super(locale);
+        const t = locale.t;
+        const helpLabel = new LabelView();
+        helpLabel.text = t('Help Contents. To close this dialog press ESC.');
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: ['ck', 'ck-accessibility-help-dialog__content'],
+                'aria-labelledby': helpLabel.id,
+                role: 'document',
+                tabindex: -1
+            },
+            children: [
+                createElement(document, 'p', {}, t('Below, you can find a list of keyboard shortcuts that can be used in the editor.')),
+                ...this._createCategories(Array.from(keystrokes.values())),
+                helpLabel
+            ]
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    focus() {
+        this.element.focus();
+    }
+    /**
+     * Creates `<section><h3>Category label</h3>...</section>` elements for each category of keystrokes.
+     */
+    _createCategories(categories) {
+        return categories.map(categoryDefinition => {
+            const elements = [
+                // Category header.
+                createElement(document, 'h3', {}, categoryDefinition.label),
+                // Category definitions (<dl>) and their optional headers (<h4>).
+                ...Array.from(categoryDefinition.groups.values())
+                    .map(groupDefinition => this._createGroup(groupDefinition))
+                    .flat()
+            ];
+            // Category description (<p>).
+            if (categoryDefinition.description) {
+                elements.splice(1, 0, createElement(document, 'p', {}, categoryDefinition.description));
+            }
+            return createElement(document, 'section', {}, elements);
+        });
+    }
+    /**
+     * Creates `[<h4>Optional label</h4>]<dl>...</dl>` elements for each group of keystrokes in a category.
+     */
+    _createGroup(groupDefinition) {
+        const definitionAndDescriptionElements = groupDefinition.keystrokes
+            .sort((a, b) => a.label.localeCompare(b.label))
+            .map(keystrokeDefinition => this._createGroupRow(keystrokeDefinition))
+            .flat();
+        const elements = [
+            createElement(document, 'dl', {}, definitionAndDescriptionElements)
+        ];
+        if (groupDefinition.label) {
+            elements.unshift(createElement(document, 'h4', {}, groupDefinition.label));
+        }
+        return elements;
+    }
+    /**
+     * Creates `<dt>Keystroke label</dt><dd>Keystroke definition</dd>` elements for each keystroke in a group.
+     */
+    _createGroupRow(keystrokeDefinition) {
+        const t = this.locale.t;
+        const dt = createElement(document, 'dt');
+        const dd = createElement(document, 'dd');
+        const normalizedKeystrokeDefinition = normalizeKeystrokeDefinition(keystrokeDefinition.keystroke);
+        const keystrokeAlternativeHTMLs = [];
+        for (const keystrokeAlternative of normalizedKeystrokeDefinition) {
+            keystrokeAlternativeHTMLs.push(keystrokeAlternative.map(keystrokeToEnvKbd).join(''));
+        }
+        dt.innerHTML = keystrokeDefinition.label;
+        dd.innerHTML = keystrokeAlternativeHTMLs.join(', ') +
+            (keystrokeDefinition.mayRequireFn && env.isMac ? ` ${t('(may require <kbd>Fn</kbd>)')}` : '');
+        return [dt, dd];
+    }
+}
+function keystrokeToEnvKbd(keystroke) {
+    return getEnvKeystrokeText(keystroke)
+        .split('+')
+        .map(part => `<kbd>${part}</kbd>`)
+        .join('+');
+}
+function normalizeKeystrokeDefinition(definition) {
+    if (typeof definition === 'string') {
+        return [[definition]];
+    }
+    if (typeof definition[0] === 'string') {
+        return [definition];
+    }
+    return definition;
+}

package/src/formheader/formheaderview.js

@@ -58,7 +58,8 @@ export default class FormHeaderView extends View {
                 class: [
                     'ck',
                     'ck-form__header__label'
-                ]
+                ],
+                role: 'presentation'
             },
             children: [
                 { text: bind.to('label') }

package/src/index.d.ts

@@ -10,6 +10,7 @@ export { default as injectCssTransitionDisabler } from './bindings/injectcsstran
 export { default as CssTransitionDisablerMixin, type ViewWithCssTransitionDisabler } from './bindings/csstransitiondisablermixin.js';
 export { default as submitHandler } from './bindings/submithandler.js';
 export { default as addKeyboardHandlingForGrid } from './bindings/addkeyboardhandlingforgrid.js';
+export { default as AccessibilityHelp } from './editorui/accessibilityhelp/accessibilityhelp.js';
 export { default as BodyCollection } from './editorui/bodycollection.js';
 export { type ButtonExecuteEvent } from './button/button.js';
 export type { default as ButtonLabel } from './button/buttonlabel.js';

package/src/index.js

@@ -10,6 +10,7 @@ export { default as injectCssTransitionDisabler } from './bindings/injectcsstran
 export { default as CssTransitionDisablerMixin } from './bindings/csstransitiondisablermixin.js';
 export { default as submitHandler } from './bindings/submithandler.js';
 export { default as addKeyboardHandlingForGrid } from './bindings/addkeyboardhandlingforgrid.js';
+export { default as AccessibilityHelp } from './editorui/accessibilityhelp/accessibilityhelp.js';
 export { default as BodyCollection } from './editorui/bodycollection.js';
 export { default as ButtonView } from './button/buttonview.js';
 export { default as ButtonLabelView } from './button/buttonlabelview.js';

package/src/toolbar/balloon/balloontoolbar.d.ts

@@ -68,11 +68,6 @@ export default class BalloonToolbar extends Plugin {
      * @inheritDoc
      */
     init(): void;
-    /**
-     * Creates toolbar components based on given configuration.
-     * This needs to be done when all plugins are ready.
-     */
-    afterInit(): void;
     /**
      * Creates the toolbar view instance.
      */

package/src/toolbar/balloon/balloontoolbar.js

@@ -117,14 +117,11 @@ export default class BalloonToolbar extends Plugin {
         this.listenTo(this.toolbarView, 'groupedItemsUpdate', () => {
             this._updatePosition();
         });
-    }
-    /**
-     * Creates toolbar components based on given configuration.
-     * This needs to be done when all plugins are ready.
-     */
-    afterInit() {
-        const factory = this.editor.ui.componentFactory;
-        this.toolbarView.fillFromConfig(this._balloonConfig, factory);
+        // Creates toolbar components based on given configuration.
+        // This needs to be done when all plugins are ready.
+        editor.ui.once('ready', () => {
+            this.toolbarView.fillFromConfig(this._balloonConfig, this.editor.ui.componentFactory);
+        });
     }
     /**
      * Creates the toolbar view instance.

package/src/toolbar/block/blocktoolbar.d.ts

@@ -75,8 +75,6 @@ export default class BlockToolbar extends Plugin {
      *
      * **Note**: Used only when `shouldNotGroupWhenFull` was **not** set in the
      * {@link module:core/editor/editorconfig~EditorConfig#blockToolbar configuration}.
-     *
-     * **Note:** Created in {@link #afterInit}.
      */
     private _resizeObserver;
     /**
@@ -95,12 +93,6 @@ export default class BlockToolbar extends Plugin {
      * @inheritDoc
      */
     init(): void;
-    /**
-     * Fills the toolbar with its items based on the configuration.
-     *
-     * **Note:** This needs to be done after all plugins are ready.
-     */
-    afterInit(): void;
     /**
      * @inheritDoc
      */

package/src/toolbar/block/blocktoolbar.js

@@ -79,8 +79,6 @@ export default class BlockToolbar extends Plugin {
          *
          * **Note**: Used only when `shouldNotGroupWhenFull` was **not** set in the
          * {@link module:core/editor/editorconfig~EditorConfig#blockToolbar configuration}.
-         *
-         * **Note:** Created in {@link #afterInit}.
          */
         this._resizeObserver = null;
         this._blockToolbarConfig = normalizeToolbarConfig(this.editor.config.get('blockToolbar'));
@@ -138,18 +136,15 @@ export default class BlockToolbar extends Plugin {
             beforeFocus: () => this._showPanel(),
             afterBlur: () => this._hidePanel()
         });
-    }
-    /**
-     * Fills the toolbar with its items based on the configuration.
-     *
-     * **Note:** This needs to be done after all plugins are ready.
-     */
-    afterInit() {
-        this.toolbarView.fillFromConfig(this._blockToolbarConfig, this.editor.ui.componentFactory);
-        // Hide panel before executing each button in the panel.
-        for (const item of this.toolbarView.items) {
-            item.on('execute', () => this._hidePanel(true), { priority: 'high' });
-        }
+        // Fills the toolbar with its items based on the configuration.
+        // This needs to be done after all plugins are ready.
+        editor.ui.once('ready', () => {
+            this.toolbarView.fillFromConfig(this._blockToolbarConfig, this.editor.ui.componentFactory);
+            // Hide panel before executing each button in the panel.
+            for (const item of this.toolbarView.items) {
+                item.on('execute', () => this._hidePanel(true), { priority: 'high' });
+            }
+        });
     }
     /**
      * @inheritDoc

package/src/tooltipmanager.d.ts

@@ -100,6 +100,10 @@ export default class TooltipManager extends TooltipManager_base {
      * {@link module:core/editor/editorconfig~EditorConfig#balloonToolbar configuration}.
      */
     private _resizeObserver;
+    /**
+     * An instance of the mutation observer that keeps track on target element attributes changes.
+     */
+    private _mutationObserver;
     /**
      * A debounced version of {@link #_pinTooltip}. Tooltips show with a delay to avoid flashing and
      * to improve the UX.
@@ -172,7 +176,7 @@ export default class TooltipManager extends TooltipManager_base {
     /**
      * Updates the position of the tooltip so it stays in sync with the element it is pinned to.
      *
-     * Hides the tooltip when the element is no longer visible in DOM.
+     * Hides the tooltip when the element is no longer visible in DOM or the tooltip text was removed.
      */
     private _updateTooltipPosition;
 }

package/src/tooltipmanager.js

@@ -87,6 +87,10 @@ class TooltipManager extends DomEmitterMixin() {
          * {@link module:core/editor/editorconfig~EditorConfig#balloonToolbar configuration}.
          */
         this._resizeObserver = null;
+        /**
+         * An instance of the mutation observer that keeps track on target element attributes changes.
+         */
+        this._mutationObserver = null;
         TooltipManager._editors.add(editor);
         // TooltipManager must be a singleton. Multiple instances would mean multiple tooltips attached
         // to the same DOM element with data-cke-tooltip-* attributes.
@@ -113,6 +117,9 @@ class TooltipManager extends DomEmitterMixin() {
         this.balloonPanelView = new BalloonPanelView(editor.locale);
         this.balloonPanelView.class = BALLOON_CLASS;
         this.balloonPanelView.content.add(this.tooltipTextView);
+        this._mutationObserver = createMutationObserver(() => {
+            this._updateTooltipPosition();
+        });
         this._pinTooltipDebounced = debounce(this._pinTooltip, 600);
         this.listenTo(global.document, 'mouseenter', this._onEnterOrFocus.bind(this), { useCapture: true });
         this.listenTo(global.document, 'mouseleave', this._onLeaveOrBlur.bind(this), { useCapture: true });
@@ -275,6 +282,7 @@ class TooltipManager extends DomEmitterMixin() {
                 this._unpinTooltip();
             }
         });
+        this._mutationObserver.attach(targetDomElement);
         this.balloonPanelView.class = [BALLOON_CLASS, cssClass]
             .filter(className => className)
             .join(' ');
@@ -301,22 +309,24 @@ class TooltipManager extends DomEmitterMixin() {
         if (this._resizeObserver) {
             this._resizeObserver.destroy();
         }
+        this._mutationObserver.detach();
     }
     /**
      * Updates the position of the tooltip so it stays in sync with the element it is pinned to.
      *
-     * Hides the tooltip when the element is no longer visible in DOM.
+     * Hides the tooltip when the element is no longer visible in DOM or the tooltip text was removed.
      */
     _updateTooltipPosition() {
+        const tooltipData = getTooltipData(this._currentElementWithTooltip);
         // This could happen if the tooltip was attached somewhere in a contextual content toolbar and the toolbar
-        // disappeared (e.g. removed an image).
-        if (!isVisible(this._currentElementWithTooltip)) {
+        // disappeared (e.g. removed an image), or the tooltip text was removed.
+        if (!isVisible(this._currentElementWithTooltip) || !tooltipData.text) {
             this._unpinTooltip();
             return;
         }
         this.balloonPanelView.pin({
             target: this._currentElementWithTooltip,
-            positions: TooltipManager.getPositioningFunctions(this._currentTooltipPosition)
+            positions: TooltipManager.getPositioningFunctions(tooltipData.position)
         });
     }
 }
@@ -352,3 +362,21 @@ function getTooltipData(element) {
         cssClass: element.dataset.ckeTooltipClass || ''
     };
 }
+// Creates a simple `MutationObserver` instance wrapper that observes changes in the tooltip-related attributes of the given element.
+// Used instead of the `MutationObserver` from the engine for simplicity.
+function createMutationObserver(callback) {
+    const mutationObserver = new MutationObserver(() => {
+        callback();
+    });
+    return {
+        attach(element) {
+            mutationObserver.observe(element, {
+                attributes: true,
+                attributeFilter: ['data-cke-tooltip-text', 'data-cke-tooltip-position']
+            });
+        },
+        detach() {
+            mutationObserver.disconnect();
+        }
+    };
+}

package/theme/components/editorui/accessibilityhelp.css

@@ -0,0 +1,10 @@
+/*
+ * 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
+ */
+
+/*
+ * Note: This file should contain the wireframe styles only. But since there are no such styles,
+ * it acts as a message to the builder telling that it should look for the corresponding styles
+ * **in the theme** when compiling the editor.
+ */

package/theme/icons/accessibility.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 20 20" xmlns="http://www.w3.org/2000/svg"><path d="M10 6.628a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3Z"/><path d="M8.5 9.125a.3.3 0 0 0-.253-.296L5.11 8.327a.75.75 0 1 1 .388-1.449l4.04.716c.267.072.624.08.893.009l4.066-.724a.75.75 0 1 1 .388 1.45l-3.132.5a.3.3 0 0 0-.253.296v1.357a.3.3 0 0 0 .018.102l1.615 4.438a.75.75 0 0 1-1.41.513l-1.35-3.71a.3.3 0 0 0-.281-.197h-.209a.3.3 0 0 0-.282.198l-1.35 3.711a.75.75 0 0 1-1.41-.513l1.64-4.509a.3.3 0 0 0 .019-.103V9.125Z"/><path clip-rule="evenodd" d="M10 18.5a8.5 8.5 0 1 1 0-17 8.5 8.5 0 0 1 0 17Zm0 1.5c5.523 0 10-4.477 10-10S15.523 0 10 0 0 4.477 0 10s4.477 10 10 10Z"/></svg>