@ckeditor/ckeditor5-ui 39.0.2 → 40.1.0

package/src/labeledfield/utils.d.ts

@@ -7,8 +7,9 @@
  */
 import InputTextView from '../inputtext/inputtextview';
 import InputNumberView from '../inputnumber/inputnumberview';
-import type LabeledFieldView from './labeledfieldview';
+import TextareaView from '../textarea/textareaview';
 import type DropdownView from '../dropdown/dropdownview';
+import type { LabeledFieldViewCreator } from './labeledfieldview';
 /**
  * A helper for creating labeled inputs.
  *
@@ -36,7 +37,7 @@ import type DropdownView from '../dropdown/dropdownview';
  * {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#statusView labeled view's status} and the input.
  * @returns The input text view instance.
  */
-export declare function createLabeledInputText(labeledFieldView: LabeledFieldView, viewUid: string, statusUid: string): InputTextView;
+declare const createLabeledInputText: LabeledFieldViewCreator<InputTextView>;
 /**
  * A helper for creating labeled number inputs.
  *
@@ -64,7 +65,35 @@ export declare function createLabeledInputText(labeledFieldView: LabeledFieldVie
  * {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#statusView labeled view's status} and the input.
  * @returns The input number view instance.
  */
-export declare function createLabeledInputNumber(labeledFieldView: LabeledFieldView, viewUid: string, statusUid: string): InputNumberView;
+declare const createLabeledInputNumber: LabeledFieldViewCreator<InputNumberView>;
+/**
+ * A helper for creating labeled textarea.
+ *
+ * It creates an instance of a {@link module:ui/textarea/textareaview~TextareaView textarea} that is
+ * logically related to a {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView labeled view} in DOM.
+ *
+ * The helper does the following:
+ *
+ * * It sets textarea's `id` and `ariaDescribedById` attributes.
+ * * It binds textarea's `isReadOnly` to the labeled view.
+ * * It binds textarea's `hasError` to the labeled view.
+ * * It enables a logic that cleans up the error when user starts typing in the textarea.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const labeledTextarea = new LabeledFieldView( locale, createLabeledTextarea );
+ * console.log( labeledTextarea.fieldView ); // A textarea instance.
+ * ```
+ *
+ * @param labeledFieldView The instance of the labeled field view.
+ * @param viewUid An UID string that allows DOM logical connection between the
+ * {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#labelView labeled view's label} and the textarea.
+ * @param statusUid An UID string that allows DOM logical connection between the
+ * {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#statusView labeled view's status} and the textarea.
+ * @returns The textarea view instance.
+ */
+declare const createLabeledTextarea: LabeledFieldViewCreator<TextareaView>;
 /**
  * A helper for creating labeled dropdowns.
  *
@@ -90,4 +119,5 @@ export declare function createLabeledInputNumber(labeledFieldView: LabeledFieldV
  * {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#statusView labeled view status} and the dropdown.
  * @returns The dropdown view instance.
  */
-export declare function createLabeledDropdown(labeledFieldView: LabeledFieldView, viewUid: string, statusUid: string): DropdownView;
+declare const createLabeledDropdown: LabeledFieldViewCreator<DropdownView>;
+export { createLabeledInputNumber, createLabeledInputText, createLabeledTextarea, createLabeledDropdown };

package/src/labeledfield/utils.js

@@ -7,6 +7,7 @@
  */
 import InputTextView from '../inputtext/inputtextview';
 import InputNumberView from '../inputnumber/inputnumberview';
+import TextareaView from '../textarea/textareaview';
 import { createDropdown } from '../dropdown/utils';
 /**
  * A helper for creating labeled inputs.
@@ -35,7 +36,7 @@ import { createDropdown } from '../dropdown/utils';
  * {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#statusView labeled view's status} and the input.
  * @returns The input text view instance.
  */
-export function createLabeledInputText(labeledFieldView, viewUid, statusUid) {
+const createLabeledInputText = (labeledFieldView, viewUid, statusUid) => {
     const inputView = new InputTextView(labeledFieldView.locale);
     inputView.set({
         id: viewUid,
@@ -50,7 +51,7 @@ export function createLabeledInputText(labeledFieldView, viewUid, statusUid) {
     });
     labeledFieldView.bind('isEmpty', 'isFocused', 'placeholder').to(inputView);
     return inputView;
-}
+};
 /**
  * A helper for creating labeled number inputs.
  *
@@ -78,7 +79,7 @@ export function createLabeledInputText(labeledFieldView, viewUid, statusUid) {
  * {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#statusView labeled view's status} and the input.
  * @returns The input number view instance.
  */
-export function createLabeledInputNumber(labeledFieldView, viewUid, statusUid) {
+const createLabeledInputNumber = (labeledFieldView, viewUid, statusUid) => {
     const inputView = new InputNumberView(labeledFieldView.locale);
     inputView.set({
         id: viewUid,
@@ -94,7 +95,50 @@ export function createLabeledInputNumber(labeledFieldView, viewUid, statusUid) {
     });
     labeledFieldView.bind('isEmpty', 'isFocused', 'placeholder').to(inputView);
     return inputView;
-}
+};
+/**
+ * A helper for creating labeled textarea.
+ *
+ * It creates an instance of a {@link module:ui/textarea/textareaview~TextareaView textarea} that is
+ * logically related to a {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView labeled view} in DOM.
+ *
+ * The helper does the following:
+ *
+ * * It sets textarea's `id` and `ariaDescribedById` attributes.
+ * * It binds textarea's `isReadOnly` to the labeled view.
+ * * It binds textarea's `hasError` to the labeled view.
+ * * It enables a logic that cleans up the error when user starts typing in the textarea.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const labeledTextarea = new LabeledFieldView( locale, createLabeledTextarea );
+ * console.log( labeledTextarea.fieldView ); // A textarea instance.
+ * ```
+ *
+ * @param labeledFieldView The instance of the labeled field view.
+ * @param viewUid An UID string that allows DOM logical connection between the
+ * {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#labelView labeled view's label} and the textarea.
+ * @param statusUid An UID string that allows DOM logical connection between the
+ * {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#statusView labeled view's status} and the textarea.
+ * @returns The textarea view instance.
+ */
+const createLabeledTextarea = (labeledFieldView, viewUid, statusUid) => {
+    const textareaView = new TextareaView(labeledFieldView.locale);
+    textareaView.set({
+        id: viewUid,
+        ariaDescribedById: statusUid
+    });
+    textareaView.bind('isReadOnly').to(labeledFieldView, 'isEnabled', value => !value);
+    textareaView.bind('hasError').to(labeledFieldView, 'errorText', value => !!value);
+    textareaView.on('input', () => {
+        // UX: Make the error text disappear and disable the error indicator as the user
+        // starts fixing the errors.
+        labeledFieldView.errorText = null;
+    });
+    labeledFieldView.bind('isEmpty', 'isFocused', 'placeholder').to(textareaView);
+    return textareaView;
+};
 /**
  * A helper for creating labeled dropdowns.
  *
@@ -120,7 +164,7 @@ export function createLabeledInputNumber(labeledFieldView, viewUid, statusUid) {
  * {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#statusView labeled view status} and the dropdown.
  * @returns The dropdown view instance.
  */
-export function createLabeledDropdown(labeledFieldView, viewUid, statusUid) {
+const createLabeledDropdown = (labeledFieldView, viewUid, statusUid) => {
     const dropdownView = createDropdown(labeledFieldView.locale);
     dropdownView.set({
         id: viewUid,
@@ -128,4 +172,5 @@ export function createLabeledDropdown(labeledFieldView, viewUid, statusUid) {
     });
     dropdownView.bind('isEnabled').to(labeledFieldView);
     return dropdownView;
-}
+};
+export { createLabeledInputNumber, createLabeledInputText, createLabeledTextarea, createLabeledDropdown };

package/src/list/listitemgroupview.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module ui/list/listitemgroupview
+ */
+import View from '../view';
+import type ViewCollection from '../viewcollection';
+import ListView from './listview';
+import LabelView from '../label/labelview';
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * The list item group view class.
+ */
+export default class ListItemGroupView extends View {
+    /**
+     * The visible label of the group.
+     *
+     * @observable
+     * @default ''
+     */
+    label: string;
+    /**
+     * Label of the group view. Its text is configurable using the {@link #label label attribute}.
+     *
+     * If a custom label view is not passed in `ListItemGroupView` constructor, the label is an instance
+     * of {@link module:ui/label/labelview~LabelView}.
+     */
+    readonly labelView: LabelView;
+    /**
+     * Collection of the child list items inside this group.
+     */
+    readonly items: ListView['items'];
+    /**
+     * Collection of the child elements of the group.
+     */
+    readonly children: ViewCollection;
+    /**
+     * Controls whether the item view is visible. Visible by default, list items are hidden
+     * using a CSS class.
+     *
+     * @observable
+     * @default true
+     */
+    isVisible: boolean;
+    /**
+     * Creates an instance of the list item group view class.
+     *
+     * @param locale The {@link module:core/editor/editor~Editor#locale} instance.
+     * @param labelView The instance of the group's label. If not provided, an instance of
+     * {@link module:ui/label/labelview~LabelView} is used.
+     */
+    constructor(locale?: Locale, labelView?: LabelView);
+    /**
+     * Focuses the list item.
+     */
+    focus(): void;
+}

package/src/list/listitemgroupview.js

@@ -0,0 +1,63 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module ui/list/listitemgroupview
+ */
+import View from '../view';
+import ListView from './listview';
+import LabelView from '../label/labelview';
+/**
+ * The list item group view class.
+ */
+export default class ListItemGroupView extends View {
+    /**
+     * Creates an instance of the list item group view class.
+     *
+     * @param locale The {@link module:core/editor/editor~Editor#locale} instance.
+     * @param labelView The instance of the group's label. If not provided, an instance of
+     * {@link module:ui/label/labelview~LabelView} is used.
+     */
+    constructor(locale, labelView = new LabelView()) {
+        super(locale);
+        const bind = this.bindTemplate;
+        const nestedList = new ListView(locale);
+        this.set({
+            label: '',
+            isVisible: true
+        });
+        this.labelView = labelView;
+        this.labelView.bind('text').to(this, 'label');
+        this.children = this.createCollection();
+        this.children.addMany([this.labelView, nestedList]);
+        nestedList.set({
+            role: 'group',
+            ariaLabelledBy: labelView.id
+        });
+        // Disable focus tracking and accessible navigation in the child list.
+        nestedList.focusTracker.destroy();
+        nestedList.keystrokes.destroy();
+        this.items = nestedList.items;
+        this.setTemplate({
+            tag: 'li',
+            attributes: {
+                role: 'presentation',
+                class: [
+                    'ck',
+                    'ck-list__group',
+                    bind.if('isVisible', 'ck-hidden', value => !value)
+                ]
+            },
+            children: this.children
+        });
+    }
+    /**
+     * Focuses the list item.
+     */
+    focus() {
+        if (this.items.first) {
+            this.items.first.focus();
+        }
+    }
+}

package/src/list/listitemview.d.ts

@@ -6,6 +6,7 @@
  * @module ui/list/listitemview
  */
 import View from '../view';
+import type { FocusableView } from '../focuscycler';
 import type ViewCollection from '../viewcollection';
 import type { Locale } from '@ckeditor/ckeditor5-utils';
 /**
@@ -15,7 +16,7 @@ export default class ListItemView extends View {
     /**
      * Collection of the child views inside of the list item {@link #element}.
      */
-    readonly children: ViewCollection;
+    readonly children: ViewCollection<FocusableView>;
     /**
      * Controls whether the item view is visible. Visible by default, list items are hidden
      * using a CSS class.

package/src/list/listitemview.js

@@ -35,6 +35,8 @@ export default class ListItemView extends View {
      * Focuses the list item.
      */
     focus() {
-        this.children.first.focus();
+        if (this.children.first) {
+            this.children.first.focus();
+        }
     }
 }

package/src/list/listview.d.ts

@@ -6,18 +6,26 @@
  * @module ui/list/listview
  */
 import View from '../view';
+import type ListItemView from './listitemview';
+import ListItemGroupView from './listitemgroupview';
 import type DropdownPanelFocusable from '../dropdown/dropdownpanelfocusable';
-import type ViewCollection from '../viewcollection';
+import ViewCollection from '../viewcollection';
 import { FocusTracker, KeystrokeHandler, type Locale } from '@ckeditor/ckeditor5-utils';
 import '../../theme/components/list/list.css';
 /**
  * The list view class.
  */
 export default class ListView extends View<HTMLUListElement> implements DropdownPanelFocusable {
+    /**
+     * The collection of focusable views in the list. It is used to determine accessible navigation
+     * between the {@link module:ui/list/listitemview~ListItemView list items} and
+     * {@link module:ui/list/listitemgroupview~ListItemGroupView list groups}.
+     */
+    readonly focusables: ViewCollection;
     /**
      * Collection of the child list views.
      */
-    readonly items: ViewCollection;
+    readonly items: ViewCollection<ListItemView | ListItemGroupView>;
     /**
      * Tracks information about DOM focus in the list.
      */
@@ -32,6 +40,12 @@ export default class ListView extends View<HTMLUListElement> implements Dropdown
      * @observable
      */
     ariaLabel: string | undefined;
+    /**
+     * (Optional) The ARIA property reflected by the `aria-ariaLabelledBy` DOM attribute used by assistive technologies.
+     *
+     * @observable
+     */
+    ariaLabelledBy?: string | undefined;
     /**
      * The property reflected by the `role` DOM attribute to be used by assistive technologies.
      *
@@ -42,6 +56,11 @@ export default class ListView extends View<HTMLUListElement> implements Dropdown
      * Helps cycling over focusable {@link #items} in the list.
      */
     private readonly _focusCycler;
+    /**
+     * A cached map of {@link module:ui/list/listitemgroupview~ListItemGroupView} to `change` event listeners for their `items`.
+     * Used for accessibility and keyboard navigation purposes.
+     */
+    private readonly _listItemGroupToChangeListeners;
     /**
      * @inheritDoc
      */
@@ -58,8 +77,46 @@ export default class ListView extends View<HTMLUListElement> implements Dropdown
      * Focuses the first focusable in {@link #items}.
      */
     focus(): void;
+    /**
+     * Focuses the first focusable in {@link #items}.
+     */
+    focusFirst(): void;
     /**
      * Focuses the last focusable in {@link #items}.
      */
     focusLast(): void;
+    /**
+     * Registers a list item view in the focus tracker.
+     *
+     * @param item The list item view to be registered.
+     * @param index Index of the list item view in the {@link #items} collection. If not specified, the item will be added at the end.
+     */
+    private _registerFocusableListItem;
+    /**
+     * Removes a list item view from the focus tracker.
+     *
+     * @param item The list item view to be removed.
+     */
+    private _deregisterFocusableListItem;
+    /**
+     * Gets a callback that will be called when the `items` collection of a {@link module:ui/list/listitemgroupview~ListItemGroupView}
+     * change.
+     *
+     * @param groupView The group view for which the callback will be created.
+     * @returns The callback function to be used for the items `change` event listener in a group.
+     */
+    private _getOnGroupItemsChangeCallback;
+    /**
+     * Registers a list item group view (and its children) in the focus tracker.
+     *
+     * @param groupView A group view to be registered.
+     * @param groupIndex Index of the group view in the {@link #items} collection. If not specified, the group will be added at the end.
+     */
+    private _registerFocusableItemsGroup;
+    /**
+     * Removes a list item group view (and its children) from the focus tracker.
+     *
+     * @param groupView The group view to be removed.
+     */
+    private _deregisterFocusableItemsGroup;
 }

package/src/list/listview.js

@@ -7,6 +7,8 @@
  */
 import View from '../view';
 import FocusCycler from '../focuscycler';
+import ListItemGroupView from './listitemgroupview';
+import ViewCollection from '../viewcollection';
 import { FocusTracker, KeystrokeHandler } from '@ckeditor/ckeditor5-utils';
 import '../../theme/components/list/list.css';
 /**
@@ -18,12 +20,18 @@ export default class ListView extends View {
      */
     constructor(locale) {
         super(locale);
+        /**
+         * A cached map of {@link module:ui/list/listitemgroupview~ListItemGroupView} to `change` event listeners for their `items`.
+         * Used for accessibility and keyboard navigation purposes.
+         */
+        this._listItemGroupToChangeListeners = new WeakMap();
         const bind = this.bindTemplate;
+        this.focusables = new ViewCollection();
         this.items = this.createCollection();
         this.focusTracker = new FocusTracker();
         this.keystrokes = new KeystrokeHandler();
         this._focusCycler = new FocusCycler({
-            focusables: this.items,
+            focusables: this.focusables,
             focusTracker: this.focusTracker,
             keystrokeHandler: this.keystrokes,
             actions: {
@@ -34,6 +42,7 @@ export default class ListView extends View {
             }
         });
         this.set('ariaLabel', undefined);
+        this.set('ariaLabelledBy', undefined);
         this.set('role', undefined);
         this.setTemplate({
             tag: 'ul',
@@ -44,7 +53,8 @@ export default class ListView extends View {
                     'ck-list'
                 ],
                 role: bind.to('role'),
-                'aria-label': bind.to('ariaLabel')
+                'aria-label': bind.to('ariaLabel'),
+                'aria-labelledby': bind.to('ariaLabelledBy')
             },
             children: this.items
         });
@@ -56,13 +66,30 @@ export default class ListView extends View {
         super.render();
         // Items added before rendering should be known to the #focusTracker.
         for (const item of this.items) {
-            this.focusTracker.add(item.element);
+            if (item instanceof ListItemGroupView) {
+                this._registerFocusableItemsGroup(item);
+            }
+            else {
+                this._registerFocusableListItem(item);
+            }
         }
-        this.items.on('add', (evt, item) => {
-            this.focusTracker.add(item.element);
-        });
-        this.items.on('remove', (evt, item) => {
-            this.focusTracker.remove(item.element);
+        this.items.on('change', (evt, data) => {
+            for (const removed of data.removed) {
+                if (removed instanceof ListItemGroupView) {
+                    this._deregisterFocusableItemsGroup(removed);
+                }
+                else {
+                    this._deregisterFocusableListItem(removed);
+                }
+            }
+            for (const added of Array.from(data.added).reverse()) {
+                if (added instanceof ListItemGroupView) {
+                    this._registerFocusableItemsGroup(added, data.index);
+                }
+                else {
+                    this._registerFocusableListItem(added, data.index);
+                }
+            }
         });
         // Start listening for the keystrokes coming from #element.
         this.keystrokes.listenTo(this.element);
@@ -81,10 +108,80 @@ export default class ListView extends View {
     focus() {
         this._focusCycler.focusFirst();
     }
+    /**
+     * Focuses the first focusable in {@link #items}.
+     */
+    focusFirst() {
+        this._focusCycler.focusFirst();
+    }
     /**
      * Focuses the last focusable in {@link #items}.
      */
     focusLast() {
         this._focusCycler.focusLast();
     }
+    /**
+     * Registers a list item view in the focus tracker.
+     *
+     * @param item The list item view to be registered.
+     * @param index Index of the list item view in the {@link #items} collection. If not specified, the item will be added at the end.
+     */
+    _registerFocusableListItem(item, index) {
+        this.focusTracker.add(item.element);
+        this.focusables.add(item, index);
+    }
+    /**
+     * Removes a list item view from the focus tracker.
+     *
+     * @param item The list item view to be removed.
+     */
+    _deregisterFocusableListItem(item) {
+        this.focusTracker.remove(item.element);
+        this.focusables.remove(item);
+    }
+    /**
+     * Gets a callback that will be called when the `items` collection of a {@link module:ui/list/listitemgroupview~ListItemGroupView}
+     * change.
+     *
+     * @param groupView The group view for which the callback will be created.
+     * @returns The callback function to be used for the items `change` event listener in a group.
+     */
+    _getOnGroupItemsChangeCallback(groupView) {
+        return (evt, data) => {
+            for (const removed of data.removed) {
+                this._deregisterFocusableListItem(removed);
+            }
+            for (const added of Array.from(data.added).reverse()) {
+                this._registerFocusableListItem(added, this.items.getIndex(groupView) + data.index);
+            }
+        };
+    }
+    /**
+     * Registers a list item group view (and its children) in the focus tracker.
+     *
+     * @param groupView A group view to be registered.
+     * @param groupIndex Index of the group view in the {@link #items} collection. If not specified, the group will be added at the end.
+     */
+    _registerFocusableItemsGroup(groupView, groupIndex) {
+        Array.from(groupView.items).forEach((child, childIndex) => {
+            const registeredChildIndex = typeof groupIndex !== 'undefined' ? groupIndex + childIndex : undefined;
+            this._registerFocusableListItem(child, registeredChildIndex);
+        });
+        const groupItemsChangeCallback = this._getOnGroupItemsChangeCallback(groupView);
+        // Cache the reference to the callback in case the group is removed (see _deregisterFocusableItemsGroup()).
+        this._listItemGroupToChangeListeners.set(groupView, groupItemsChangeCallback);
+        groupView.items.on('change', groupItemsChangeCallback);
+    }
+    /**
+     * Removes a list item group view (and its children) from the focus tracker.
+     *
+     * @param groupView The group view to be removed.
+     */
+    _deregisterFocusableItemsGroup(groupView) {
+        for (const child of groupView.items) {
+            this._deregisterFocusableListItem(child);
+        }
+        groupView.items.off('change', this._listItemGroupToChangeListeners.get(groupView));
+        this._listItemGroupToChangeListeners.delete(groupView);
+    }
 }

package/src/panel/balloon/balloonpanelview.js

@@ -11,6 +11,22 @@ import { isElement } from 'lodash-es';
 import '../../../theme/components/panel/balloonpanel.css';
 const toPx = toUnit('px');
 const defaultLimiterElement = global.document.body;
+// A static balloon panel positioning function that moves the balloon far off the viewport.
+// It is used as a fallback when there is no way to position the balloon using provided
+// positioning functions (see: `getOptimalPosition()`), for instance, when the target the
+// balloon should be attached to gets obscured by scrollable containers or the viewport.
+//
+// It prevents the balloon from being attached to the void and possible degradation of the UX.
+// At the same time, it keeps the balloon physically visible in the DOM so the focus remains
+// uninterrupted.
+const POSITION_OFF_SCREEN = {
+    top: -99999,
+    left: -99999,
+    name: 'arrowless',
+    config: {
+        withArrow: false
+    }
+};
 /**
  * The balloon panel view class.
  *
@@ -153,7 +169,7 @@ export default class BalloonPanelView extends View {
             limiter: defaultLimiterElement,
             fitInViewport: true
         }, options);
-        const optimalPosition = BalloonPanelView._getOptimalPosition(positionOptions);
+        const optimalPosition = BalloonPanelView._getOptimalPosition(positionOptions) || POSITION_OFF_SCREEN;
         // Usually browsers make some problems with super accurate values like 104.345px
         // so it is better to use int values.
         const left = parseInt(optimalPosition.left);
@@ -953,12 +969,18 @@ export function generatePositions(options = {}) {
             ...(config && { config })
         }),
         // ------- Sticky
-        viewportStickyNorth: (targetRect, balloonRect, viewportRect) => {
-            if (!targetRect.getIntersection(viewportRect)) {
+        viewportStickyNorth: (targetRect, balloonRect, viewportRect, limiterRect) => {
+            const boundaryRect = limiterRect || viewportRect;
+            if (!targetRect.getIntersection(boundaryRect)) {
+                return null;
+            }
+            // Engage when the target top and bottom edges are close or off the boundary.
+            // By close, it means there's not enough space for the balloon arrow (offset).
+            if (boundaryRect.height - targetRect.height > stickyVerticalOffset) {
                 return null;
             }
             return {
-                top: viewportRect.top + stickyVerticalOffset,
+                top: boundaryRect.top + stickyVerticalOffset,
                 left: targetRect.left + targetRect.width / 2 - balloonRect.width / 2,
                 name: 'arrowless',
                 config: {

package/src/panel/sticky/stickypanelview.d.ts

@@ -125,10 +125,8 @@ export default class StickyPanelView extends View {
     /**
      * Analyzes the environment to decide whether the panel should be sticky or not.
      * Then handles the positioning of the panel.
-     *
-     * @param [scrollTarget] The element which is being scrolled.
      */
-    checkIfShouldBeSticky(scrollTarget?: HTMLElement | Document): void;
+    checkIfShouldBeSticky(): void;
     /**
      * Sticks the panel at the given CSS `top` offset.
      *