@ckeditor/ckeditor5-ui 0.0.0-internal-20241017.0

package/src/editableui/editableuiview.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/editableui/editableuiview
+ */
+import View from '../view.js';
+/**
+ * The editable UI view class.
+ */
+export default class EditableUIView extends View {
+    /**
+     * Creates an instance of EditableUIView class.
+     *
+     * @param locale The locale instance.
+     * @param editingView The editing view instance the editable is related to.
+     * @param editableElement The editable element. If not specified, this view
+     * should create it. Otherwise, the existing element should be used.
+     */
+    constructor(locale, editingView, editableElement) {
+        super(locale);
+        /**
+         * The name of the editable UI view.
+         */
+        this.name = null;
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-content',
+                    'ck-editor__editable',
+                    'ck-rounded-corners'
+                ],
+                lang: locale.contentLanguage,
+                dir: locale.contentLanguageDirection
+            }
+        });
+        this.set('isFocused', false);
+        this._editableElement = editableElement;
+        this._hasExternalElement = !!this._editableElement;
+        this._editingView = editingView;
+    }
+    /**
+     * Renders the view by either applying the {@link #template} to the existing
+     * {@link module:ui/editableui/editableuiview~EditableUIView#_editableElement} or assigning {@link #element}
+     * as {@link module:ui/editableui/editableuiview~EditableUIView#_editableElement}.
+     */
+    render() {
+        super.render();
+        if (this._hasExternalElement) {
+            this.template.apply(this.element = this._editableElement);
+        }
+        else {
+            this._editableElement = this.element;
+        }
+        this.on('change:isFocused', () => this._updateIsFocusedClasses());
+        this._updateIsFocusedClasses();
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        if (this._hasExternalElement) {
+            this.template.revert(this._editableElement);
+        }
+        super.destroy();
+    }
+    /**
+     * Whether an external {@link #_editableElement} was passed into the constructor, which also means
+     * the view will not render its {@link #template}.
+     */
+    get hasExternalElement() {
+        return this._hasExternalElement;
+    }
+    /**
+     * Updates the `ck-focused` and `ck-blurred` CSS classes on the {@link #element} according to
+     * the {@link #isFocused} property value using the {@link #_editingView editing view} API.
+     */
+    _updateIsFocusedClasses() {
+        const editingView = this._editingView;
+        if (editingView.isRenderingInProgress) {
+            updateAfterRender(this);
+        }
+        else {
+            update(this);
+        }
+        function update(view) {
+            editingView.change(writer => {
+                const viewRoot = editingView.document.getRoot(view.name);
+                writer.addClass(view.isFocused ? 'ck-focused' : 'ck-blurred', viewRoot);
+                writer.removeClass(view.isFocused ? 'ck-blurred' : 'ck-focused', viewRoot);
+            });
+        }
+        // In a case of a multi-root editor, a callback will be attached more than once (one callback for each root).
+        // While executing one callback the `isRenderingInProgress` observable is changing what causes executing another
+        // callback and render is called inside the already pending render.
+        // We need to be sure that callback is executed only when the value has changed from `true` to `false`.
+        // See https://github.com/ckeditor/ckeditor5/issues/1676.
+        function updateAfterRender(view) {
+            editingView.once('change:isRenderingInProgress', (evt, name, value) => {
+                if (!value) {
+                    update(view);
+                }
+                else {
+                    updateAfterRender(view);
+                }
+            });
+        }
+    }
+}

package/src/editableui/inline/inlineeditableuiview.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @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/editableui/inline/inlineeditableuiview
+ */
+import EditableUIView from '../editableuiview.js';
+import type { EditingView } from '@ckeditor/ckeditor5-engine';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * The inline editable UI class implementing an inline {@link module:ui/editableui/editableuiview~EditableUIView}.
+ */
+export default class InlineEditableUIView extends EditableUIView {
+    /**
+     * The cached options object passed to the constructor.
+     */
+    private readonly _options;
+    /**
+     * Creates an instance of the InlineEditableUIView class.
+     *
+     * @param locale The locale instance.
+     * @param editingView The editing view instance the editable is related to.
+     * @param editableElement The editable element. If not specified, the
+     * {@link module:ui/editableui/editableuiview~EditableUIView}
+     * will create it. Otherwise, the existing element will be used.
+     * @param options Additional configuration of the view.
+     * @param options.label The label of the editable for assistive technologies. If not provided, a default label is used or,
+     * the existing `aria-label` attribute value from the specified `editableElement` is preserved.
+     */
+    constructor(locale: Locale, editingView: EditingView, editableElement?: HTMLElement, options?: InlineEditableUIViewOptions);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Returns a normalized label for the editable view based on the environment.
+     */
+    getEditableAriaLabel(): string;
+}
+type InlineEditableUIViewOptions = {
+    label?: ((view: InlineEditableUIView) => string) | string | Record<string, string>;
+};
+export {};

package/src/editableui/inline/inlineeditableuiview.js

@@ -0,0 +1,71 @@
+/**
+ * @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/editableui/inline/inlineeditableuiview
+ */
+import EditableUIView from '../editableuiview.js';
+/**
+ * The inline editable UI class implementing an inline {@link module:ui/editableui/editableuiview~EditableUIView}.
+ */
+export default class InlineEditableUIView extends EditableUIView {
+    /**
+     * Creates an instance of the InlineEditableUIView class.
+     *
+     * @param locale The locale instance.
+     * @param editingView The editing view instance the editable is related to.
+     * @param editableElement The editable element. If not specified, the
+     * {@link module:ui/editableui/editableuiview~EditableUIView}
+     * will create it. Otherwise, the existing element will be used.
+     * @param options Additional configuration of the view.
+     * @param options.label The label of the editable for assistive technologies. If not provided, a default label is used or,
+     * the existing `aria-label` attribute value from the specified `editableElement` is preserved.
+     */
+    constructor(locale, editingView, editableElement, options = {}) {
+        super(locale, editingView, editableElement);
+        this._options = options;
+        this.extendTemplate({
+            attributes: {
+                role: 'textbox',
+                class: 'ck-editor__editable_inline'
+            }
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        const editingView = this._editingView;
+        editingView.change(writer => {
+            const viewRoot = editingView.document.getRoot(this.name);
+            writer.setAttribute('aria-label', this.getEditableAriaLabel(), viewRoot);
+        });
+    }
+    /**
+     * Returns a normalized label for the editable view based on the environment.
+     */
+    getEditableAriaLabel() {
+        const t = this.locale.t;
+        const label = this._options.label;
+        const editableElement = this._editableElement;
+        const editableName = this.name;
+        if (typeof label == 'string') {
+            return label;
+        }
+        else if (typeof label === 'object') {
+            return label[editableName];
+        }
+        else if (typeof label === 'function') {
+            return label(this);
+        }
+        else if (editableElement) {
+            const existingLabel = editableElement.getAttribute('aria-label');
+            if (existingLabel) {
+                return existingLabel;
+            }
+        }
+        return t('Rich Text Editor. Editing area: %0', editableName);
+    }
+}

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

@@ -0,0 +1,55 @@
+/**
+ * @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 '../../dialog/dialog.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
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Creates a button to show accessibility help dialog, for use either in toolbar or in menu bar.
+     */
+    private _createButton;
+    /**
+     * 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 _toggleDialog;
+}

package/src/editorui/accessibilityhelp/accessibilityhelp.js

@@ -0,0 +1,145 @@
+/**
+ * @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 from '../../button/buttonview.js';
+import Dialog from '../../dialog/dialog.js';
+import MenuBarMenuListItemButtonView from '../../menubar/menubarmenulistitembuttonview.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
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        const t = editor.locale.t;
+        editor.ui.componentFactory.add('accessibilityHelp', () => {
+            const button = this._createButton(ButtonView);
+            button.set({
+                tooltip: true,
+                withText: false,
+                label: t('Accessibility help')
+            });
+            return button;
+        });
+        editor.ui.componentFactory.add('menuBar:accessibilityHelp', () => {
+            const button = this._createButton(MenuBarMenuListItemButtonView);
+            button.label = t('Accessibility');
+            return button;
+        });
+        editor.keystrokes.set('Alt+0', (evt, cancel) => {
+            this._toggleDialog();
+            cancel();
+        });
+        this._setupRootLabels();
+    }
+    /**
+     * Creates a button to show accessibility help dialog, for use either in toolbar or in menu bar.
+     */
+    _createButton(ButtonClass) {
+        const editor = this.editor;
+        const dialog = editor.plugins.get('Dialog');
+        const locale = editor.locale;
+        const view = new ButtonClass(locale);
+        view.set({
+            keystroke: 'Alt+0',
+            icon: accessibilityIcon,
+            isToggleable: true
+        });
+        view.on('execute', () => this._toggleDialog());
+        view.bind('isOn').to(dialog, 'id', id => id === 'accessibilityHelp');
+        return view;
+    }
+    /**
+     * 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')])]
+                .filter(segment => segment)
+                .join('. ');
+            writer.setAttribute('aria-label', newAriaLabel, viewRoot);
+        }
+    }
+    /**
+     * Shows the accessibility help dialog. Also, creates {@link #contentView} on demand.
+     */
+    _toggleDialog() {
+        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);
+        }
+        if (dialog.id === 'accessibilityHelp') {
+            dialog.hide();
+        }
+        else {
+            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/editorui/bodycollection.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @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 ViewCollection from '../viewcollection.js';
+import type View from '../view.js';
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * This is a special {@link module:ui/viewcollection~ViewCollection} dedicated to elements that are detached
+ * from the DOM structure of the editor, like panels, icons, etc.
+ *
+ * The body collection is available in the {@link module:ui/editorui/editoruiview~EditorUIView#body `editor.ui.view.body`} property.
+ * Any plugin can add a {@link module:ui/view~View view} to this collection.
+ * These views will render in a container placed directly in the `<body>` element.
+ * The editor will detach and destroy this collection when the editor will be {@link module:core/editor/editor~Editor#destroy destroyed}.
+ *
+ * If you need to control the life cycle of the body collection on your own, you can create your own instance of this class.
+ *
+ * A body collection will render itself automatically in the DOM body element as soon as you call {@link ~BodyCollection#attachToDom}.
+ * If you create multiple body collections, this class will create a special wrapper element in the DOM to limit the number of
+ * elements created directly in the body and remove it when the last body collection will be
+ * {@link ~BodyCollection#detachFromDom detached}.
+ */
+export default class BodyCollection extends ViewCollection {
+    /**
+     * The {@link module:core/editor/editor~Editor#locale editor's locale} instance.
+     * See the view {@link module:ui/view~View#locale locale} property.
+     */
+    readonly locale: Locale;
+    /**
+     * The element holding elements of the body region.
+     */
+    private _bodyCollectionContainer?;
+    /**
+     * Creates a new instance of the {@link module:ui/editorui/bodycollection~BodyCollection}.
+     *
+     * @param locale The {@link module:core/editor/editor~Editor editor's locale} instance.
+     * @param initialItems The initial items of the collection.
+     */
+    constructor(locale: Locale, initialItems?: Iterable<View>);
+    /**
+     * The element holding elements of the body region.
+     */
+    get bodyCollectionContainer(): HTMLElement | undefined;
+    /**
+     * Attaches the body collection to the DOM body element. You need to execute this method to render the content of
+     * the body collection.
+     */
+    attachToDom(): void;
+    /**
+     * Detaches the collection from the DOM structure. Use this method when you do not need to use the body collection
+     * anymore to clean-up the DOM structure.
+     */
+    detachFromDom(): void;
+}