@ckeditor/ckeditor5-ui 41.3.1 → 41.4.0

package/dist/types/panel/balloon/contextualballoon.d.ts

@@ -0,0 +1,303 @@
+/**
+ * @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
+ */
+/**
+ * @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/panel/balloon/contextualballoon
+ */
+import BalloonPanelView from './balloonpanelview.js';
+import View from '../../view.js';
+import ButtonView from '../../button/buttonview.js';
+import type ViewCollection from '../../viewcollection.js';
+import { Plugin, type Editor } from '@ckeditor/ckeditor5-core';
+import { FocusTracker, type Locale, type PositionOptions } from '@ckeditor/ckeditor5-utils';
+import '../../../theme/components/panel/balloonrotator.css';
+import '../../../theme/components/panel/fakepanel.css';
+/**
+ * Provides the common contextual balloon for the editor.
+ *
+ * The role of this plugin is to unify the contextual balloons logic, simplify views management and help
+ * avoid the unnecessary complexity of handling multiple {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView}
+ * instances in the editor.
+ *
+ * This plugin allows for creating single or multiple panel stacks.
+ *
+ * Each stack may have multiple views, with the one on the top being visible. When the visible view is removed from the stack,
+ * the previous view becomes visible.
+ *
+ * It might be useful to implement nested navigation in a balloon. For instance, a toolbar view may contain a link button.
+ * When you click it, a link view (which lets you set the URL) is created and put on top of the toolbar view, so the link panel
+ * is displayed. When you finish editing the link and close (remove) the link view, the toolbar view is visible again.
+ *
+ * However, there are cases when there are multiple independent balloons to be displayed, for instance, if the selection
+ * is inside two inline comments at the same time. For such cases, you can create two independent panel stacks.
+ * The contextual balloon plugin will create a navigation bar to let the users switch between these panel stacks using the "Next"
+ * and "Previous" buttons.
+ *
+ * If there are no views in the current stack, the balloon panel will try to switch to the next stack. If there are no
+ * panels in any stack, the balloon panel will be hidden.
+ *
+ * **Note**: To force the balloon panel to show only one view, even if there are other stacks, use the `singleViewMode=true` option
+ * when {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon#add adding} a view to a panel.
+ *
+ * From the implementation point of view, the contextual ballon plugin is reusing a single
+ * {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView} instance to display multiple contextual balloon
+ * panels in the editor. It also creates a special {@link module:ui/panel/balloon/contextualballoon~RotatorView rotator view},
+ * used to manage multiple panel stacks. Rotator view is a child of the balloon panel view and the parent of the specific
+ * view you want to display. If there is more than one panel stack to be displayed, the rotator view will add a
+ * navigation bar. If there is only one stack, the rotator view is transparent (it does not add any UI elements).
+ */
+export default class ContextualBalloon extends Plugin {
+    /**
+     * The {@link module:utils/dom/position~Options#limiter position limiter}
+     * for the {@link #view balloon}, used when no `limiter` has been passed into {@link #add}
+     * or {@link #updatePosition}.
+     *
+     * By default, a function that obtains the farthest DOM
+     * {@link module:engine/view/rooteditableelement~RootEditableElement}
+     * of the {@link module:engine/view/document~Document#selection}.
+     */
+    positionLimiter: PositionOptions['limiter'];
+    visibleStack?: string;
+    /**
+     * The currently visible view or `null` when there are no views in any stack.
+     *
+     * @readonly
+     * @observable
+     */
+    visibleView: View | null;
+    /**
+     * A total number of all stacks in the balloon.
+     *
+     * @private
+     * @readonly
+     * @observable
+     */
+    _numberOfStacks: number;
+    /**
+     * A flag that controls the single view mode.
+     *
+     * @private
+     * @readonly
+     * @observable
+     */
+    _singleViewMode: boolean;
+    /**
+     * The map of views and their stacks.
+     */
+    private _viewToStack;
+    /**
+     * The map of IDs and stacks.
+     */
+    private _idToStack;
+    /**
+     * The common balloon panel view.
+     */
+    private _view;
+    /**
+     * Rotator view embedded in the contextual balloon.
+     * Displays the currently visible view in the balloon and provides navigation for switching stacks.
+     */
+    private _rotatorView;
+    /**
+     * Displays fake panels under the balloon panel view when multiple stacks are added to the balloon.
+     */
+    private _fakePanelsView;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ContextualBalloon";
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * The common balloon panel view.
+     */
+    get view(): BalloonPanelView;
+    /**
+     * Returns `true` when the given view is in one of the stacks. Otherwise returns `false`.
+     */
+    hasView(view: View): boolean;
+    /**
+     * Adds a new view to the stack and makes it visible if the current stack is visible
+     * or it is the first view in the balloon.
+     *
+     * @param data The configuration of the view.
+     * @param data.stackId The ID of the stack that the view is added to. Defaults to `'main'`.
+     * @param data.view The content of the balloon.
+     * @param data.position Positioning options.
+     * @param data.balloonClassName An additional CSS class added to the {@link #view balloon} when visible.
+     * @param data.withArrow Whether the {@link #view balloon} should be rendered with an arrow. Defaults to `true`.
+     * @param data.singleViewMode Whether the view should be the only visible view even if other stacks were added. Defaults to `false`.
+     */
+    add(data: ViewConfiguration): void;
+    /**
+     * Removes the given view from the stack. If the removed view was visible,
+     * the view preceding it in the stack will become visible instead.
+     * When there is no view in the stack, the next stack will be displayed.
+     * When there are no more stacks, the balloon will hide.
+     *
+     * @param view A view to be removed from the balloon.
+     */
+    remove(view: View): void;
+    /**
+     * Updates the position of the balloon using the position data of the first visible view in the stack.
+     * When new position data is given, the position data of the currently visible view will be updated.
+     *
+     * @param position Position options.
+     */
+    updatePosition(position?: Partial<PositionOptions>): void;
+    /**
+     * Shows the last view from the stack of a given ID.
+     */
+    showStack(id: string): void;
+    /**
+     * Initializes view instances.
+     */
+    private _createPanelView;
+    /**
+     * Returns the stack of the currently visible view.
+     */
+    private get _visibleStack();
+    /**
+     * Returns the ID of the given stack.
+     */
+    private _getStackId;
+    /**
+     * Shows the last view from the next stack.
+     */
+    private _showNextStack;
+    /**
+     * Shows the last view from the previous stack.
+     */
+    private _showPrevStack;
+    /**
+     * Creates a rotator view.
+     */
+    private _createRotatorView;
+    /**
+     * Creates a fake panels view.
+     */
+    private _createFakePanelsView;
+    /**
+     * Sets the view as the content of the balloon and attaches the balloon using position
+     * options of the first view.
+     *
+     * @param data Configuration.
+     * @param data.view The view to show in the balloon.
+     * @param data.balloonClassName Additional class name which will be added to the {@link #view balloon}.
+     * @param data.withArrow Whether the {@link #view balloon} should be rendered with an arrow.
+     */
+    private _showView;
+    /**
+     * Returns position options of the last view in the stack.
+     * This keeps the balloon in the same position when the view is changed.
+     */
+    private _getBalloonPosition;
+}
+/**
+ * The configuration of the view.
+ */
+export interface ViewConfiguration {
+    /**
+     * The ID of the stack that the view is added to.
+     *
+     * @default 'main'
+     */
+    stackId?: string;
+    /**
+     * The content of the balloon.
+     */
+    view: View;
+    /**
+     * Positioning options.
+     */
+    position?: Partial<PositionOptions>;
+    /**
+     * An additional CSS class added to the {@link #view balloon} when visible.
+     */
+    balloonClassName?: string;
+    /**
+     * Whether the {@link #view balloon} should be rendered with an arrow.
+     *
+     * @default true
+     */
+    withArrow?: boolean;
+    /**
+     * Whether the view should be the only visible view even if other stacks were added.
+     *
+     * @default false
+     */
+    singleViewMode?: boolean;
+}
+/**
+ * Rotator view is a helper class for the {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon ContextualBalloon}.
+ * It is used for displaying the last view from the current stack and providing navigation buttons for switching stacks.
+ * See the {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon ContextualBalloon} documentation to learn more.
+ */
+export declare class RotatorView extends View {
+    /**
+     * Used for checking if a view is focused or not.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * Navigation button for switching the stack to the previous one.
+     */
+    readonly buttonPrevView: ButtonView;
+    /**
+     * Navigation button for switching the stack to the next one.
+     */
+    readonly buttonNextView: ButtonView;
+    /**
+     * A collection of the child views that creates the rotator content.
+     */
+    readonly content: ViewCollection;
+    /**
+     * Defines whether navigation is visible or not.
+     *
+     * @observable
+     */
+    isNavigationVisible: boolean;
+    /**
+     * @observable
+     */
+    counter: string;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Shows a given view.
+     *
+     * @param view The view to show.
+     */
+    showView(view: View): void;
+    /**
+     * Hides the currently displayed view.
+     */
+    hideView(): void;
+    /**
+     * Creates a navigation button view.
+     *
+     * @param label The button label.
+     * @param icon The button icon.
+     */
+    private _createButtonView;
+}

package/dist/types/panel/sticky/stickypanelview.d.ts

@@ -0,0 +1,160 @@
+/**
+ * @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
+ */
+/**
+ * @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/panel/sticky/stickypanelview
+ */
+import View from '../../view.js';
+import type ViewCollection from '../../viewcollection.js';
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+import '../../../theme/components/panel/stickypanel.css';
+/**
+ * The sticky panel view class.
+ */
+export default class StickyPanelView extends View {
+    /**
+     * Collection of the child views which creates balloon panel contents.
+     */
+    readonly content: ViewCollection;
+    /**
+     * Controls whether the sticky panel should be active.
+     *
+     * @readonly
+     * @observable
+     */
+    isActive: boolean;
+    /**
+     * Controls whether the sticky panel is in the "sticky" state.
+     *
+     * @readonly
+     * @observable
+     */
+    isSticky: boolean;
+    /**
+     * The limiter element for the sticky panel instance. Its bounding rect limits
+     * the "stickyness" of the panel, i.e. when the panel reaches the bottom
+     * edge of the limiter, it becomes sticky to that edge and does not float
+     * off the limiter. It is mandatory for the panel to work properly and once
+     * set, it cannot be changed.
+     *
+     * @readonly
+     * @observable
+     */
+    limiterElement: HTMLElement | null;
+    /**
+     * The offset from the bottom edge of {@link #limiterElement}
+     * which stops the panel from stickying any further to prevent limiter's content
+     * from being completely covered.
+     *
+     * @readonly
+     * @observable
+     * @default 50
+     */
+    limiterBottomOffset: number;
+    /**
+     * The offset from the top edge of the web browser's viewport which makes the
+     * panel become sticky. The default value is `0`, which means the panel becomes
+     * sticky when it's upper edge touches the top of the page viewport.
+     *
+     * This attribute is useful when the web page has UI elements positioned to the top
+     * either using `position: fixed` or `position: sticky`, which would cover the
+     * sticky panel or vice–versa (depending on the `z-index` hierarchy).
+     *
+     * Bound to {@link module:ui/editorui/editorui~EditorUI#viewportOffset `EditorUI#viewportOffset`}.
+     *
+     * If {@link module:core/editor/editorconfig~EditorConfig#ui `EditorConfig#ui.viewportOffset.top`} is defined, then
+     * it will override the default value.
+     *
+     * @observable
+     * @default 0
+     */
+    viewportTopOffset: number;
+    /**
+     * The panel which accepts children into {@link #content} collection.
+     * Also an element which is positioned when {@link #isSticky}.
+     */
+    contentPanelElement: HTMLElement;
+    /**
+     * Controls the `margin-left` CSS style of the panel.
+     *
+     * @private
+     * @readonly
+     * @observable
+     */
+    _marginLeft: string | null;
+    /**
+     * Set `true` if the sticky panel reached the bottom edge of the
+     * {@link #limiterElement}.
+     *
+     * @private
+     * @readonly
+     * @observable
+     */
+    _isStickyToTheBottomOfLimiter: boolean;
+    /**
+     * The `top` CSS position of the panel when it is sticky to the top of the viewport or scrollable
+     * ancestors of the {@link #limiterElement}.
+     *
+     * @private
+     * @readonly
+     * @observable
+     */
+    _stickyTopOffset: number | null;
+    /**
+     * The `bottom` CSS position of the panel when it is sticky to the bottom of the {@link #limiterElement}.
+     *
+     * @private
+     * @readonly
+     * @observable
+     */
+    _stickyBottomOffset: number | null;
+    /**
+     * A dummy element which visually fills the space as long as the
+     * actual panel is sticky. It prevents flickering of the UI.
+     */
+    private _contentPanelPlaceholder;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Analyzes the environment to decide whether the panel should be sticky or not.
+     * Then handles the positioning of the panel.
+     */
+    checkIfShouldBeSticky(): void;
+    /**
+     * Sticks the panel at the given CSS `top` offset.
+     *
+     * @private
+     * @param topOffset
+     */
+    private _stickToTopOfAncestors;
+    /**
+     * Sticks the panel at the bottom of the limiter with a given CSS `bottom` offset.
+     *
+     * @private
+     * @param stickyBottomOffset
+     */
+    private _stickToBottomOfLimiter;
+    /**
+     * Unsticks the panel putting it back to its original position.
+     *
+     * @private
+     */
+    private _unstick;
+    /**
+     * Returns the bounding rect of the {@link #contentPanelElement}.
+     *
+     * @private
+     */
+    private get _contentPanelRect();
+}

package/dist/types/search/filteredview.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
+ */
+/**
+ * @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 type { FocusableView } from '../focuscycler.js';
+/**
+ * @module ui/search/filteredview
+ */
+/**
+ * A view that can be filtered by a {@link module:ui/search/text/searchtextview~SearchTextView}.
+ */
+export default interface FilteredView extends FocusableView {
+    /**
+     * Filters the view by the given regular expression.
+     */
+    filter(regExp: RegExp | null): {
+        resultsCount: number;
+        totalItemsCount: number;
+    };
+}
+/**
+ * Fired when the user selects an autocomplete option. The event data should contain the selected value.
+ *
+ * @eventName ~FilteredView#execute
+ */
+export interface FilteredViewExecuteEvent {
+    name: 'execute';
+    args: [{
+        value: string;
+    }];
+}

package/dist/types/search/searchinfoview.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @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
+ */
+/**
+ * @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/search/searchinfoview
+*/
+import type { FocusableView } from '../focuscycler.js';
+import View from '../view.js';
+/**
+ * A view displaying an information text related to different states of {@link module:ui/search/text/searchtextview~SearchTextView}.
+ *
+ * @internal
+ */
+export default class SearchInfoView extends View implements FocusableView {
+    /**
+     * Controls whether the view is visible.
+     *
+     * @observable
+     * @default false
+     */
+    isVisible: boolean;
+    /**
+     * Controls the primary line of text in the info.
+     *
+     * @observable
+     * @default ''
+     */
+    primaryText: string;
+    /**
+     * Controls the secondary line of text in the info.
+     *
+     * @observable
+     * @default ''
+     */
+    secondaryText: string;
+    /**
+     * @inheritDoc
+     */
+    constructor();
+    /**
+     * Focuses the view
+     */
+    focus(): void;
+}

package/dist/types/search/searchresultsview.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @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
+ */
+/**
+ * @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/search/searchresultsview
+ */
+import View from '../view.js';
+import type ViewCollection from '../viewcollection.js';
+import { FocusTracker, type Locale } from '@ckeditor/ckeditor5-utils';
+import { default as FocusCycler, type FocusableView } from '../focuscycler.js';
+/**
+ * A sub-component of {@link module:ui/search/text/searchtextview~SearchTextView}. It hosts the filtered and the information views.
+ */
+export default class SearchResultsView extends View implements FocusableView {
+    /**
+     * Tracks information about the DOM focus in the view.
+     *
+     * @readonly
+     */
+    focusTracker: FocusTracker;
+    /**
+     * The collection of the child views inside of the list item {@link #element}.
+     *
+     * @readonly
+     */
+    children: ViewCollection<FocusableView>;
+    /**
+     * Provides the focus management (keyboard navigation) in the view.
+     *
+     * @readonly
+     */
+    protected _focusCycler: FocusCycler;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Focuses the view.
+     */
+    focus(): void;
+    /**
+     * Focuses the first child view.
+     */
+    focusFirst(): void;
+    /**
+     * Focuses the last child view.
+     */
+    focusLast(): void;
+}

package/dist/types/search/text/searchtextqueryview.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @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
+ */
+/**
+ * @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/search/text/searchtextqueryview
+ */
+import ButtonView from '../../button/buttonview.js';
+import IconView from '../../icon/iconview.js';
+import LabeledFieldView, { type LabeledFieldViewCreator } from '../../labeledfield/labeledfieldview.js';
+import type InputBase from '../../input/inputbase.js';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * A search input field for the {@link module:ui/search/text/searchtextview~SearchTextView} component.
+ *
+ * @internal
+ * @extends module:ui/labeledfield/labeledfieldview~LabeledFieldView
+ */
+export default class SearchTextQueryView<TQueryFieldView extends InputBase<HTMLInputElement | HTMLTextAreaElement>> extends LabeledFieldView<TQueryFieldView> {
+    /**
+     * The loupe icon displayed next to the {@link #fieldView}.
+     */
+    iconView?: IconView;
+    /**
+     * The button that clears and focuses the {@link #fieldView}.
+     */
+    resetButtonView?: ButtonView;
+    /**
+     * A reference to the view configuration.
+     */
+    private readonly _viewConfig;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale, config: SearchTextQueryViewConfig<TQueryFieldView>);
+    /**
+     * Resets the search field to its default state.
+     */
+    reset(): void;
+}
+/**
+ * An event fired when the field is reset using the
+ * {@link module:ui/search/text/searchtextqueryview~SearchTextQueryView#resetButtonView}.
+ *
+ * @eventName ~SearchTextQueryView#reset
+ */
+export type SearchTextQueryViewResetEvent = {
+    name: 'reset';
+    args: [];
+};
+/**
+ * The configuration of the {@link module:ui/search/text/searchtextqueryview~SearchTextQueryView} view.
+ */
+export interface SearchTextQueryViewConfig<TConfigSearchField extends InputBase<HTMLInputElement | HTMLTextAreaElement>> {
+    /**
+     * The human-readable label of the search field.
+     */
+    label: string;
+    /**
+     * Determines whether the button that resets the search should be visible.
+     *
+     * @default true
+     */
+    showResetButton?: boolean;
+    /**
+     * Determines whether the loupe icon should be visible.
+     *
+     * @default true
+     */
+    showIcon?: boolean;
+    /**
+     * The function that creates the search field input view. By default, a plain
+     * {@link module:ui/inputtext/inputtextview~InputTextView} is used for this purpose.
+     */
+    creator?: LabeledFieldViewCreator<TConfigSearchField>;
+}