@ckeditor/ckeditor5-ui 0.0.0-internal-20241017.0

package/src/dropdown/button/splitbuttonview.d.ts

@@ -0,0 +1,162 @@
+/**
+ * @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/dropdown/button/splitbuttonview
+ */
+import View from '../../view.js';
+import ButtonView from '../../button/buttonview.js';
+import type ViewCollection from '../../viewcollection.js';
+import type Button from '../../button/button.js';
+import type DropdownButton from './dropdownbutton.js';
+import type { FocusableView } from '../../focuscycler.js';
+import { KeystrokeHandler, FocusTracker, type Locale } from '@ckeditor/ckeditor5-utils';
+import '../../../theme/components/dropdown/splitbutton.css';
+/**
+ * The split button view class.
+ *
+ * ```ts
+ * const view = new SplitButtonView();
+ *
+ * view.set( {
+ * 	label: 'A button',
+ * 	keystroke: 'Ctrl+B',
+ * 	tooltip: true
+ * } );
+ *
+ * view.render();
+ *
+ * document.body.append( view.element );
+ * ```
+ *
+ * Also see the {@link module:ui/dropdown/utils~createDropdown `createDropdown()` util}.
+ */
+export default class SplitButtonView extends View<HTMLDivElement> implements DropdownButton {
+    /**
+     * Collection of the child views inside of the split button {@link #element}.
+     */
+    readonly children: ViewCollection;
+    /**
+     * A main button of split button.
+     */
+    readonly actionView: ButtonView;
+    /**
+     * A secondary button of split button that opens dropdown.
+     */
+    readonly arrowView: ButtonView;
+    /**
+     * Instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}. It manages
+     * keystrokes of the split button:
+     *
+     * * <kbd>▶</kbd> moves focus to arrow view when action view is focused,
+     * * <kbd>◀</kbd> moves focus to action view when arrow view is focused.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * Tracks information about DOM focus in the dropdown.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * @inheritDoc
+     */
+    label: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    keystroke: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    tooltip: Button['tooltip'];
+    /**
+     * @inheritDoc
+     */
+    tooltipPosition: Button['tooltipPosition'];
+    /**
+     * @inheritDoc
+     */
+    type: Button['type'];
+    /**
+     * @inheritDoc
+     */
+    isOn: boolean;
+    /**
+     * @inheritDoc
+     */
+    isEnabled: boolean;
+    /**
+     * @inheritDoc
+     */
+    isVisible: boolean;
+    /**
+     * @inheritDoc
+     */
+    isToggleable: boolean;
+    /**
+     * @inheritDoc
+     */
+    withText: boolean;
+    /**
+     * @inheritDoc
+     */
+    withKeystroke: boolean;
+    /**
+     * @inheritDoc
+     */
+    icon: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    tabindex: number;
+    /**
+     * @inheritDoc
+     */
+    class: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    labelStyle: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    role: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    ariaChecked: boolean | undefined;
+    /**
+     * @inheritDoc
+     */
+    ariaLabel?: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    ariaLabelledBy: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale, actionButton?: ButtonView & FocusableView);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the {@link module:ui/button/buttonview~ButtonView#element} of the action part of split button.
+     */
+    focus(): void;
+    /**
+     * Creates a {@link module:ui/button/buttonview~ButtonView} instance as {@link #actionView} and binds it with main split button
+     * attributes.
+     */
+    private _createActionView;
+    /**
+     * Creates a {@link module:ui/button/buttonview~ButtonView} instance as {@link #arrowView} and binds it with main split button
+     * attributes.
+     */
+    private _createArrowView;
+}

package/src/dropdown/button/splitbuttonview.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 ui/dropdown/button/splitbuttonview
+ */
+import View from '../../view.js';
+import ButtonView from '../../button/buttonview.js';
+import { KeystrokeHandler, FocusTracker } from '@ckeditor/ckeditor5-utils';
+import dropdownArrowIcon from '../../../theme/icons/dropdown-arrow.svg';
+import '../../../theme/components/dropdown/splitbutton.css';
+/**
+ * The split button view class.
+ *
+ * ```ts
+ * const view = new SplitButtonView();
+ *
+ * view.set( {
+ * 	label: 'A button',
+ * 	keystroke: 'Ctrl+B',
+ * 	tooltip: true
+ * } );
+ *
+ * view.render();
+ *
+ * document.body.append( view.element );
+ * ```
+ *
+ * Also see the {@link module:ui/dropdown/utils~createDropdown `createDropdown()` util}.
+ */
+export default class SplitButtonView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale, actionButton) {
+        super(locale);
+        const bind = this.bindTemplate;
+        // Implement the Button interface.
+        this.set('class', undefined);
+        this.set('labelStyle', undefined);
+        this.set('icon', undefined);
+        this.set('isEnabled', true);
+        this.set('isOn', false);
+        this.set('isToggleable', false);
+        this.set('isVisible', true);
+        this.set('keystroke', undefined);
+        this.set('withKeystroke', false);
+        this.set('label', undefined);
+        this.set('tabindex', -1);
+        this.set('tooltip', false);
+        this.set('tooltipPosition', 's');
+        this.set('type', 'button');
+        this.set('withText', false);
+        this.children = this.createCollection();
+        this.actionView = this._createActionView(actionButton);
+        this.arrowView = this._createArrowView();
+        this.keystrokes = new KeystrokeHandler();
+        this.focusTracker = new FocusTracker();
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-splitbutton',
+                    bind.to('class'),
+                    bind.if('isVisible', 'ck-hidden', value => !value),
+                    this.arrowView.bindTemplate.if('isOn', 'ck-splitbutton_open')
+                ]
+            },
+            children: this.children
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        this.children.add(this.actionView);
+        this.children.add(this.arrowView);
+        this.focusTracker.add(this.actionView.element);
+        this.focusTracker.add(this.arrowView.element);
+        this.keystrokes.listenTo(this.element);
+        // Overrides toolbar focus cycling behavior.
+        this.keystrokes.set('arrowright', (evt, cancel) => {
+            if (this.focusTracker.focusedElement === this.actionView.element) {
+                this.arrowView.focus();
+                cancel();
+            }
+        });
+        // Overrides toolbar focus cycling behavior.
+        this.keystrokes.set('arrowleft', (evt, cancel) => {
+            if (this.focusTracker.focusedElement === this.arrowView.element) {
+                this.actionView.focus();
+                cancel();
+            }
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        this.focusTracker.destroy();
+        this.keystrokes.destroy();
+    }
+    /**
+     * Focuses the {@link module:ui/button/buttonview~ButtonView#element} of the action part of split button.
+     */
+    focus() {
+        this.actionView.focus();
+    }
+    /**
+     * Creates a {@link module:ui/button/buttonview~ButtonView} instance as {@link #actionView} and binds it with main split button
+     * attributes.
+     */
+    _createActionView(actionButton) {
+        const actionView = actionButton || new ButtonView();
+        if (!actionButton) {
+            actionView.bind('icon', 'isEnabled', 'isOn', 'isToggleable', 'keystroke', 'label', 'tabindex', 'tooltip', 'tooltipPosition', 'type', 'withText').to(this);
+        }
+        actionView.extendTemplate({
+            attributes: {
+                class: 'ck-splitbutton__action'
+            }
+        });
+        actionView.delegate('execute').to(this);
+        return actionView;
+    }
+    /**
+     * Creates a {@link module:ui/button/buttonview~ButtonView} instance as {@link #arrowView} and binds it with main split button
+     * attributes.
+     */
+    _createArrowView() {
+        const arrowView = new ButtonView();
+        const bind = arrowView.bindTemplate;
+        arrowView.icon = dropdownArrowIcon;
+        arrowView.extendTemplate({
+            attributes: {
+                class: [
+                    'ck-splitbutton__arrow'
+                ],
+                'data-cke-tooltip-disabled': bind.to('isOn'),
+                'aria-haspopup': true,
+                'aria-expanded': bind.to('isOn', value => String(value))
+            }
+        });
+        arrowView.bind('isEnabled').to(this);
+        arrowView.bind('label').to(this);
+        arrowView.bind('tooltip').to(this);
+        arrowView.delegate('execute').to(this, 'open');
+        return arrowView;
+    }
+}

package/src/dropdown/dropdownpanelfocusable.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @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/dropdown/dropdownpanelfocusable
+ */
+/**
+ * The dropdown panel interface for focusable contents. It provides two methods for managing focus of the contents
+ * of dropdown's panel.
+ */
+export default interface DropdownPanelFocusable {
+    /**
+     * Focuses the view element or first item in view collection on opening dropdown's panel.
+     */
+    focus(): void;
+    /**
+     * Focuses the view element or last item in view collection on opening dropdown's panel.
+     */
+    focusLast(): void;
+}

package/src/dropdown/dropdownpanelfocusable.js

@@ -0,0 +1,5 @@
+/**
+ * @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
+ */
+export {};

package/src/dropdown/dropdownpanelview.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @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/dropdown/dropdownpanelview
+ */
+import View from '../view.js';
+import type ViewCollection from '../viewcollection.js';
+import type DropdownPanelFocusable from './dropdownpanelfocusable.js';
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * The dropdown panel view class.
+ *
+ * See {@link module:ui/dropdown/dropdownview~DropdownView} to learn about the common usage.
+ */
+export default class DropdownPanelView extends View implements DropdownPanelFocusable {
+    /**
+     * Collection of the child views in this panel.
+     *
+     * A common child type is the {@link module:ui/list/listview~ListView} and {@link module:ui/toolbar/toolbarview~ToolbarView}.
+     * See {@link module:ui/dropdown/utils~addListToDropdown} and
+     * {@link module:ui/dropdown/utils~addToolbarToDropdown} to learn more about child views of dropdowns.
+     */
+    readonly children: ViewCollection;
+    /**
+     * Controls whether the panel is visible.
+     *
+     * @observable
+     */
+    isVisible: boolean;
+    /**
+     * The position of the panel, relative to the parent.
+     *
+     * This property is reflected in the CSS class set to {@link #element} that controls
+     * the position of the panel.
+     *
+     * @observable
+     * @default 'se'
+     */
+    position: PanelPosition;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+    /**
+     * Focuses the first view in the {@link #children} collection.
+     *
+     * See also {@link module:ui/dropdown/dropdownpanelfocusable~DropdownPanelFocusable}.
+     */
+    focus(): void;
+    /**
+     * Focuses the view element or last item in view collection on opening dropdown's panel.
+     *
+     * See also {@link module:ui/dropdown/dropdownpanelfocusable~DropdownPanelFocusable}.
+     */
+    focusLast(): void;
+}
+/**
+ * The position of the panel, relative to the parent.
+ */
+export type PanelPosition = 's' | 'se' | 'sw' | 'sme' | 'smw' | 'n' | 'ne' | 'nw' | 'nme' | 'nmw';

package/src/dropdown/dropdownpanelview.js

@@ -0,0 +1,97 @@
+/**
+ * @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/dropdown/dropdownpanelview
+ */
+import View from '../view.js';
+import { logWarning } from '@ckeditor/ckeditor5-utils';
+/**
+ * The dropdown panel view class.
+ *
+ * See {@link module:ui/dropdown/dropdownview~DropdownView} to learn about the common usage.
+ */
+export default class DropdownPanelView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale) {
+        super(locale);
+        const bind = this.bindTemplate;
+        this.set('isVisible', false);
+        this.set('position', 'se');
+        this.children = this.createCollection();
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-reset',
+                    'ck-dropdown__panel',
+                    bind.to('position', value => `ck-dropdown__panel_${value}`),
+                    bind.if('isVisible', 'ck-dropdown__panel-visible')
+                ],
+                tabindex: '-1'
+            },
+            children: this.children,
+            on: {
+                // Drag and drop in the panel should not break the selection in the editor.
+                // https://github.com/ckeditor/ckeditor5-ui/issues/228
+                selectstart: bind.to(evt => {
+                    if (evt.target.tagName.toLocaleLowerCase() === 'input') {
+                        return;
+                    }
+                    evt.preventDefault();
+                })
+            }
+        });
+    }
+    /**
+     * Focuses the first view in the {@link #children} collection.
+     *
+     * See also {@link module:ui/dropdown/dropdownpanelfocusable~DropdownPanelFocusable}.
+     */
+    focus() {
+        if (this.children.length) {
+            const firstChild = this.children.first;
+            if (typeof firstChild.focus === 'function') {
+                firstChild.focus();
+            }
+            else {
+                /**
+                 * The child view of a dropdown could not be focused because it is missing the `focus()` method.
+                 *
+                 * This warning appears when a dropdown {@link module:ui/dropdown/dropdownview~DropdownView#isOpen gets open} and it
+                 * attempts to focus the {@link module:ui/dropdown/dropdownpanelview~DropdownPanelView#children first child} of its panel
+                 * but the child does not implement the
+                 * {@link module:ui/dropdown/dropdownpanelfocusable~DropdownPanelFocusable focusable interface}.
+                 *
+                 * Focusing the content of a dropdown on open greatly improves the accessibility. Please make sure the view instance
+                 * provides the `focus()` method for the best user experience.
+                 *
+                 * @error ui-dropdown-panel-focus-child-missing-focus
+                 * @param childView
+                 * @param dropdownPanel
+                 */
+                logWarning('ui-dropdown-panel-focus-child-missing-focus', { childView: this.children.first, dropdownPanel: this });
+            }
+        }
+    }
+    /**
+     * Focuses the view element or last item in view collection on opening dropdown's panel.
+     *
+     * See also {@link module:ui/dropdown/dropdownpanelfocusable~DropdownPanelFocusable}.
+     */
+    focusLast() {
+        if (this.children.length) {
+            const lastChild = this.children.last;
+            if (typeof lastChild.focusLast === 'function') {
+                lastChild.focusLast();
+            }
+            else {
+                lastChild.focus();
+            }
+        }
+    }
+}