@tylertech/forge 3.11.0 → 3.12.1

package/esm/list-dropdown/list-dropdown-core.js

@@ -135,7 +135,7 @@ export class ListDropdownCore {
     get dropdownElement() {
         return this._adapter.dropdownElement;
     }
-    scrollSelectedOptionIntoView(animate = true) {
+    scrollSelectedOptionIntoView(animate) {
         this._adapter.scrollSelectedOptionIntoView(animate);
     }
     setScrollBottomListener(listener, threshold) {

package/esm/list-dropdown/list-dropdown-utils.d.ts

@@ -6,7 +6,7 @@
 import { ILinearProgressComponent } from '../linear-progress';
 import { IListComponent } from '../list/list';
 import { IPopoverComponent } from '../popover/popover';
-import { IListDropdownOpenConfig, IListDropdownOption, IListDropdownOptionGroup, ListDropdownAsyncStyle } from './list-dropdown-constants';
+import { IListDropdownOpenConfig, IListDropdownOption, IListDropdownOptionGroup, ListDropdownAsyncStyle, ListDropdownTooltipConfig } from './list-dropdown-constants';
 export declare enum ListDropdownOptionType {
     Option = 0,
     Group = 1
@@ -24,6 +24,8 @@ export declare function createList(config: IListDropdownOpenConfig): IListCompon
  * @param config
  */
 export declare function createListItems(config: IListDropdownOpenConfig, listElement: IListComponent, options?: Array<IListDropdownOption | IListDropdownOptionGroup>, startIndex?: number, renderSelected?: boolean): void;
+export declare function createListItemTooltip(tooltip: ListDropdownTooltipConfig, configId: string, optionIdIndex: number, listItemElement: HTMLElement, buttonElement: HTMLElement): HTMLElement;
+export declare function asyncCreateListItemTooltipIfTextOverflows(tooltip: ListDropdownTooltipConfig, configId: string, optionIdIndex: number, listItemElement: HTMLElement, buttonElement: HTMLElement, secondaryLabelElement: HTMLElement): Promise<void>;
 export declare function createCheckboxElement(selected: boolean): HTMLElement;
 export declare function createAsyncElement(asyncStyle?: ListDropdownAsyncStyle): HTMLElement;
 export declare function createBusyElement(): ILinearProgressComponent;

package/esm/list-dropdown/list-dropdown-utils.js

@@ -11,6 +11,7 @@ import { LIST_CONSTANTS } from '../list/list';
 import { POPOVER_CONSTANTS } from '../popover';
 import { SKELETON_CONSTANTS } from '../skeleton';
 import { ListDropdownAsyncStyle, ListDropdownType, LIST_DROPDOWN_CONSTANTS } from './list-dropdown-constants';
+import { frame } from '../core/utils/utils';
 export var ListDropdownOptionType;
 (function (ListDropdownOptionType) {
     ListDropdownOptionType[ListDropdownOptionType["Option"] = 0] = "Option";
@@ -66,6 +67,9 @@ export function createPopupDropdown(config, targetElement) {
     if (config.popupShift !== undefined) {
         popoverElement.shift = config.popupShift;
     }
+    if (config.anchorAccessibility) {
+        popoverElement.anchorAccessibility = config.anchorAccessibility;
+    }
     // Set the animations based on our type
     if (config.type === ListDropdownType.None) {
         popoverElement.animationType = 'none';
@@ -220,7 +224,7 @@ export function createListItems(config, listElement, options, startIndex = 0, re
                     buttonElement.textContent = option.label || '';
                 }
                 else {
-                    const result = config.transform(option.label);
+                    const result = config.transform(option.label, option, isSelected);
                     if (typeof result === 'string') {
                         buttonElement.textContent = result;
                     }
@@ -229,27 +233,9 @@ export function createListItems(config, listElement, options, startIndex = 0, re
                     }
                 }
             }
-            // Check for a tooltip configuration
-            if (option.tooltip) {
-                const { text, type = 'presentation', ...restConfig } = option.tooltip;
-                const tooltipElement = document.createElement('forge-tooltip');
-                tooltipElement.id = `list-dropdown-option-${config.id}-${optionIdIndex++}-tooltip`;
-                tooltipElement.textContent = option.tooltip.text;
-                // We always anchor to the list item element unless an anchor element is provided
-                if (!option.tooltip.anchor && !option.tooltip.anchorElement) {
-                    tooltipElement.anchorElement = listItemElement;
-                }
-                // We need to attach the tooltip ARIA attributes to the button element, not the anchor element
-                if (type === 'label' || type === 'description') {
-                    const a11yAttr = type === 'label' ? 'aria-labelledby' : 'aria-describedby';
-                    buttonElement.setAttribute(a11yAttr, tooltipElement.id);
-                }
-                Object.assign(tooltipElement, restConfig);
-                listItemElement.appendChild(tooltipElement);
-            }
+            const secondaryLabelElement = document.createElement('span');
             // Check for secondary (subtitle) text
             if (option.secondaryLabel) {
-                const secondaryLabelElement = document.createElement('span');
                 secondaryLabelElement.slot = 'secondary-text';
                 secondaryLabelElement.textContent = option.secondaryLabel;
                 secondaryLabelElement.id = `list-dropdown-option-${config.id}-${optionIdIndex++}-secondary`;
@@ -257,6 +243,16 @@ export function createListItems(config, listElement, options, startIndex = 0, re
                 listItemElement.appendChild(secondaryLabelElement);
                 buttonElement.setAttribute('aria-describedby', secondaryLabelElement.id);
             }
+            // Check for a tooltip configuration
+            if (option.tooltip) {
+                if (!isDefined(option.tooltip?.visibilityMode) || option.tooltip?.visibilityMode === 'always') {
+                    const tooltipElement = createListItemTooltip(option.tooltip, config.id, optionIdIndex, listItemElement, buttonElement);
+                    listItemElement.appendChild(tooltipElement);
+                }
+                else if (option.tooltip?.visibilityMode === 'overflow-only') {
+                    asyncCreateListItemTooltipIfTextOverflows(option.tooltip, config.id, optionIdIndex, listItemElement, buttonElement, secondaryLabelElement);
+                }
+            }
             // If multiple selections are enabled then we need to create and append a leading checkbox element
             if (config.multiple) {
                 const checkboxElement = createCheckboxElement(isSelected);
@@ -330,6 +326,31 @@ export function createListItems(config, listElement, options, startIndex = 0, re
         }
     }
 }
+export function createListItemTooltip(tooltip, configId, optionIdIndex, listItemElement, buttonElement) {
+    const { text, type = 'presentation', ...restConfig } = tooltip;
+    const tooltipElement = document.createElement('forge-tooltip');
+    tooltipElement.id = `list-dropdown-option-${configId}-${optionIdIndex++}-tooltip`;
+    tooltipElement.textContent = tooltip.text;
+    // We always anchor to the list item element unless an anchor element is provided
+    if (!tooltip.anchor && !tooltip.anchorElement) {
+        tooltipElement.anchorElement = listItemElement;
+    }
+    // We need to attach the tooltip ARIA attributes to the button element, not the anchor element
+    if (type === 'label' || type === 'description') {
+        const a11yAttr = type === 'label' ? 'aria-labelledby' : 'aria-describedby';
+        buttonElement.setAttribute(a11yAttr, tooltipElement.id);
+    }
+    Object.assign(tooltipElement, restConfig);
+    return tooltipElement;
+}
+export async function asyncCreateListItemTooltipIfTextOverflows(tooltip, configId, optionIdIndex, listItemElement, buttonElement, secondaryLabelElement) {
+    await frame();
+    // Only append the tooltip if the button or secondary label overflow the width of the parent list item.
+    if (buttonElement.scrollWidth > buttonElement.clientWidth || secondaryLabelElement.scrollWidth > secondaryLabelElement.clientWidth) {
+        const tooltipElement = createListItemTooltip(tooltip, configId, optionIdIndex, listItemElement, buttonElement);
+        listItemElement.appendChild(tooltipElement);
+    }
+}
 export function createCheckboxElement(selected) {
     const checkboxElement = document.createElement('forge-icon');
     checkboxElement.setAttribute(LIST_DROPDOWN_CONSTANTS.attributes.CHECKBOX_ELEMENT, '');

package/esm/list-dropdown/list-dropdown.js

@@ -69,7 +69,7 @@ export class ListDropdown {
         this._core.appendOptions(options);
     }
     scrollSelectedOptionIntoView(animate) {
-        this._core.scrollSelectedOptionIntoView();
+        this._core.scrollSelectedOptionIntoView(animate);
     }
     setScrollBottomListener(listener, threshold) {
         this._core.setScrollBottomListener(listener, threshold);

package/esm/menu/menu-adapter.d.ts

@@ -35,6 +35,7 @@ export interface IMenuAdapter extends IBaseAdapter {
     createChildMenu(index: number, parentValue: any, openCb: (index: number) => void, closeCb: (index: number) => void, selectCb: (data: IMenuSelectEventData) => void): IMenuComponent;
     closeOtherChildMenus(excludeIndex?: number): void;
     setSelectedValues(values: any[]): void;
+    resolvePopupTargetById(id: string | null): HTMLElement | null;
 }
 export declare class MenuAdapter extends BaseAdapter<IMenuComponent> implements IMenuAdapter {
     private _targetElement;
@@ -70,4 +71,5 @@ export declare class MenuAdapter extends BaseAdapter<IMenuComponent> implements
     private _getOpenChildMenu;
     private _getOwnList;
     private _getListItems;
+    resolvePopupTargetById(id: string | null): HTMLElement | null;
 }

package/esm/menu/menu-adapter.js

@@ -40,20 +40,16 @@ export class MenuAdapter extends BaseAdapter {
         }
     }
     addTargetListener(event, callback, bubbles = false) {
-        if (this._targetElement) {
-            this._targetElement.addEventListener(event, callback, bubbles);
-        }
+        this._targetElement?.addEventListener(event, callback, bubbles);
     }
     removeTargetListener(event, callback) {
-        if (this._targetElement) {
-            this._targetElement.removeEventListener(event, callback);
-        }
+        this._targetElement?.removeEventListener(event, callback);
     }
     attachMenu(config) {
-        if (this._listDropdown || !this._targetElement) {
+        if (this._listDropdown || !this._targetElement || !config.referenceElement) {
             return;
         }
-        this._listDropdown = new ListDropdown(this._targetElement, config);
+        this._listDropdown = new ListDropdown(config.referenceElement, config);
         this._listDropdown.open();
         this._targetElement.setAttribute('aria-expanded', 'true');
         this._targetElement.setAttribute('aria-controls', `list-dropdown-popup-${config.id}`);
@@ -201,4 +197,12 @@ export class MenuAdapter extends BaseAdapter {
         }
         return [];
     }
+    resolvePopupTargetById(id) {
+        if (!id) {
+            return null;
+        }
+        const root = this._component.getRootNode();
+        const contextDocument = root instanceof Document || root instanceof ShadowRoot ? root : document;
+        return contextDocument.getElementById(id);
+    }
 }

package/esm/menu/menu-constants.d.ts

@@ -27,6 +27,7 @@ export declare const MENU_CONSTANTS: {
         OPTION_LIMIT: string;
         OBSERVE_SCROLL: string;
         OBSERVE_SCROLL_THRESHOLD: string;
+        POPUP_TARGET: string;
     };
     events: {
         SELECT: string;

package/esm/menu/menu-constants.js

@@ -9,7 +9,7 @@ const classes = {
     POPUP: 'forge-menu__popup'
 };
 const selectors = {
-    TOGGLE: `.${elementName}__toggle,[${elementName}-toggle],forge-button,forge-icon-button,forge-fab,button,[type=button],[role=button],a,forge-list-item,[tabindex]:not([tabindex^="-"])`,
+    TOGGLE: `.${elementName}__toggle,[${elementName}-toggle],forge-button,forge-icon-button,forge-fab,button,[type=button],[role=button],a,forge-list-item > button,[tabindex]:not([tabindex^="-"])`,
     MENU_LIST: 'forge-list'
 };
 const attributes = {
@@ -25,7 +25,8 @@ const attributes = {
     POPUP_CLASSES: 'popup-classes',
     OPTION_LIMIT: 'option-limit',
     OBSERVE_SCROLL: 'observe-scroll',
-    OBSERVE_SCROLL_THRESHOLD: 'observe-scroll-threshold'
+    OBSERVE_SCROLL_THRESHOLD: 'observe-scroll-threshold',
+    POPUP_TARGET: 'popup-target'
 };
 const events = {
     SELECT: `${elementName}-select`,

package/esm/menu/menu-core.d.ts

@@ -26,6 +26,7 @@ export interface IMenuCore {
     mode: MenuMode;
     popupOffset: IOverlayOffset;
     optionBuilder: MenuOptionBuilder | undefined;
+    popupTarget: string | null;
     activateFirstOption(): void;
 }
 export declare class MenuCore extends CascadingListDropdownAwareCore<IMenuOption | IMenuOptionGroup> implements IMenuCore {
@@ -40,6 +41,7 @@ export declare class MenuCore extends CascadingListDropdownAwareCore<IMenuOption
     private _mode;
     private _popupOffset;
     private _optionBuilder;
+    private _popupTarget;
     private _identifier;
     private _clickListener;
     private _blurListener;
@@ -82,6 +84,7 @@ export declare class MenuCore extends CascadingListDropdownAwareCore<IMenuOption
     protected _setCascadeTargetInactive(): void;
     protected _isOwnElement(element: Element): boolean;
     private _createCascadingElement;
+    private _tryResolvePopupTarget;
     private _mapIconToLeadingIcon;
     get open(): boolean;
     set open(value: boolean);
@@ -106,6 +109,8 @@ export declare class MenuCore extends CascadingListDropdownAwareCore<IMenuOption
     set mode(value: MenuMode);
     get popupOffset(): IOverlayOffset;
     set popupOffset(value: IOverlayOffset);
+    get popupTarget(): string | null;
+    set popupTarget(value: string | null);
     get optionBuilder(): MenuOptionBuilder | undefined;
     set optionBuilder(cb: MenuOptionBuilder | undefined);
     get popupElement(): HTMLElement | null;

package/esm/menu/menu-core.js

@@ -21,6 +21,7 @@ export class MenuCore extends CascadingListDropdownAwareCore {
         this._iconClass = ICON_CLASS_NAME;
         this._persistSelection = false;
         this._mode = 'click';
+        this._popupTarget = null;
         this._identifier = randomChars();
         this._clickListener = evt => this._onTargetClick(evt);
         this._blurListener = evt => this._onTargetBlur(evt);
@@ -218,9 +219,22 @@ export class MenuCore extends CascadingListDropdownAwareCore {
         }
         this._mapIconToLeadingIcon();
         const selectedValues = this._persistSelection ? this._getSelectedValues() : [];
+        let referenceElement = this._adapter.targetElement;
+        if (this._popupTarget) {
+            const popupTargetElement = this._adapter.resolvePopupTargetById(this._popupTarget);
+            if (popupTargetElement) {
+                referenceElement = popupTargetElement;
+            }
+        }
+        else {
+            const resolvedTarget = this._tryResolvePopupTarget();
+            if (resolvedTarget) {
+                referenceElement = resolvedTarget;
+            }
+        }
         const config = {
             id: this._identifier,
-            referenceElement: this._adapter.targetElement,
+            referenceElement,
             type: ListDropdownType.Menu,
             options: this._options,
             selectedValues,
@@ -246,7 +260,8 @@ export class MenuCore extends CascadingListDropdownAwareCore {
             activeChangeCallback: this._activeChangeListener,
             selectCallback: this._selectListener,
             popupOffset: this._popupOffset,
-            cascadingElementFactory: params => this._createCascadingElement(params)
+            cascadingElementFactory: params => this._createCascadingElement(params),
+            anchorAccessibility: 'none'
         };
         this._adapter.setHostAttribute(MENU_CONSTANTS.attributes.OPEN, '');
         this._adapter.attachMenu(config);
@@ -391,6 +406,15 @@ export class MenuCore extends CascadingListDropdownAwareCore {
         menu.iconClass = this._iconClass;
         return menu;
     }
+    _tryResolvePopupTarget() {
+        if (this._popupTarget) {
+            return;
+        }
+        // Automatically detect forge-list-item > button case and set popup target if not explicitly set
+        if (this._adapter.targetElement?.matches('button')) {
+            return this._adapter.targetElement.closest('forge-list-item') ?? undefined;
+        }
+    }
     _mapIconToLeadingIcon() {
         // For backwards compatibility with old API, map the old "icon" property to the new "leadingIcon" property (if exists)
         this._flatOptions.filter(o => o.icon).forEach(o => (o.leadingIcon = o.icon));
@@ -516,6 +540,21 @@ export class MenuCore extends CascadingListDropdownAwareCore {
     set popupOffset(value) {
         this._popupOffset = value;
     }
+    get popupTarget() {
+        return this._popupTarget ?? null;
+    }
+    set popupTarget(value) {
+        value = value ?? null;
+        if (this._popupTarget !== value) {
+            this._popupTarget = value;
+            if (this._popupTarget) {
+                this._adapter.setHostAttribute(MENU_CONSTANTS.attributes.POPUP_TARGET, this._popupTarget);
+            }
+            else {
+                this._adapter.removeHostAttribute(MENU_CONSTANTS.attributes.POPUP_TARGET);
+            }
+        }
+    }
     get optionBuilder() {
         return this._optionBuilder;
     }

package/esm/menu/menu.d.ts

@@ -21,6 +21,7 @@ export interface IMenuComponent extends IListDropdownAware {
     popupOffset: IOverlayOffset;
     optionBuilder: MenuOptionBuilder | undefined;
     popupElement: HTMLElement | undefined;
+    popupTarget: string | null;
     propagateKeyEvent(evt: KeyboardEvent): void;
     activateFirstOption(): void;
 }
@@ -38,10 +39,15 @@ declare global {
 /**
  * @tag forge-menu
  *
- * @summary Menus display a list of options or actions that users can select from a dropdown.
+ * @summary Menus display a list of options or actions that users can select from a dropdown. Menus wrap button or list item elements to provide the trigger for displaying the menu options.
  *
  * @dependency forge-popover
  * @dependency forge-list
+ *
+ * @event {CustomEvent<IMenuSelectEventData>} forge-menu-select - Dispatches when a menu option is selected.
+ * @event {CustomEvent<void>} forge-menu-open - Dispatches when the menu is opened.
+ * @event {CustomEvent<void>} forge-menu-close - Dispatches when the menu is closed.
+ * @event {CustomEvent<IMenuActiveChangeEventData>} forge-menu-active-change - Dispatches when the active menu option changes.
  */
 export declare class MenuComponent extends ListDropdownAware implements IMenuComponent {
     static get observedAttributes(): string[];
@@ -119,6 +125,15 @@ export declare class MenuComponent extends ListDropdownAware implements IMenuCom
      * @readonly
      */
     popupElement: HTMLElement | undefined;
+    /**
+     * Gets/sets the ID of the element to use as the popup anchor for positioning.
+     * When null or empty, the target element (button) is used for both interaction and positioning.
+     * This is useful for cases like forge-list-item > button where the menu should be
+     * attached to the button for listeners but positioned relative to the list item.
+     * @default null
+     * @attribute popup-target
+     */
+    popupTarget: string | null;
     /**
      * Force propagates the key event from another element to this component.
      */

package/esm/menu/menu.js

@@ -19,10 +19,15 @@ const styles = ':host{display:inline-flex}:host([hidden]){display:none}';
 /**
  * @tag forge-menu
  *
- * @summary Menus display a list of options or actions that users can select from a dropdown.
+ * @summary Menus display a list of options or actions that users can select from a dropdown. Menus wrap button or list item elements to provide the trigger for displaying the menu options.
  *
  * @dependency forge-popover
  * @dependency forge-list
+ *
+ * @event {CustomEvent<IMenuSelectEventData>} forge-menu-select - Dispatches when a menu option is selected.
+ * @event {CustomEvent<void>} forge-menu-open - Dispatches when the menu is opened.
+ * @event {CustomEvent<void>} forge-menu-close - Dispatches when the menu is closed.
+ * @event {CustomEvent<IMenuActiveChangeEventData>} forge-menu-active-change - Dispatches when the active menu option changes.
  */
 let MenuComponent = class MenuComponent extends ListDropdownAware {
     static get observedAttributes() {
@@ -40,7 +45,8 @@ let MenuComponent = class MenuComponent extends ListDropdownAware {
             MENU_CONSTANTS.attributes.POPUP_CLASSES,
             MENU_CONSTANTS.attributes.OPTION_LIMIT,
             MENU_CONSTANTS.attributes.OBSERVE_SCROLL,
-            MENU_CONSTANTS.attributes.OBSERVE_SCROLL_THRESHOLD
+            MENU_CONSTANTS.attributes.OBSERVE_SCROLL_THRESHOLD,
+            MENU_CONSTANTS.attributes.POPUP_TARGET
         ];
     }
     constructor() {
@@ -84,6 +90,9 @@ let MenuComponent = class MenuComponent extends ListDropdownAware {
             case MENU_CONSTANTS.attributes.MODE:
                 this.mode = newValue;
                 break;
+            case MENU_CONSTANTS.attributes.POPUP_TARGET:
+                this._core.popupTarget = isDefined(newValue) ? newValue : null;
+                break;
         }
     }
     disconnectedCallback() {
@@ -141,6 +150,9 @@ __decorate([
 __decorate([
     coreProperty({ set: false })
 ], MenuComponent.prototype, "popupElement", void 0);
+__decorate([
+    coreProperty()
+], MenuComponent.prototype, "popupTarget", void 0);
 MenuComponent = __decorate([
     customElement({
         name: MENU_CONSTANTS.elementName,

package/esm/open-icon/open-icon.d.ts

@@ -18,7 +18,8 @@ declare global {
 /**
  * @tag forge-open-icon
  *
- * @summary Open icons are used to indicate whether a section is open or closed.
+ * @summary Open icons are icons used to indicate whether a section is open or closed. They provide an animated transition between the two states to enhance the user experience.
+ 
  *
  * @property {boolean} [open=false] - Whether the icon is open or closed.
  * @property {OpenIconOrientation} [orientation=vertical] - The orientation of the rotation.

package/esm/open-icon/open-icon.js

@@ -14,7 +14,8 @@ const styles = ':host{display:inline-flex}:host([hidden]){display:none}.forge-op
 /**
  * @tag forge-open-icon
  *
- * @summary Open icons are used to indicate whether a section is open or closed.
+ * @summary Open icons are icons used to indicate whether a section is open or closed. They provide an animated transition between the two states to enhance the user experience.
+ 
  *
  * @property {boolean} [open=false] - Whether the icon is open or closed.
  * @property {OpenIconOrientation} [orientation=vertical] - The orientation of the rotation.

package/esm/overlay/overlay.d.ts

@@ -21,8 +21,7 @@ declare global {
 /**
  * @tag forge-overlay
  *
- * @summary Overlays are used to render content in an element that rendered above all content on the page,
- * and positioned around a specified anchor element.
+ * @summary Overlays are used to show content in an element that is rendered above all other content on the page, and positioned around a specified anchor element. This is a low-level building block component that does not provide any visual styles, but is used within other components such as popovers, and tooltips.
  *
  * @description
  * An overlay is a low-level building block component that does not provide any visual styles. Its only

package/esm/overlay/overlay.js

@@ -15,8 +15,7 @@ const styles = ':host{display:contents}:host([hidden]){display:none}.forge-overl
 /**
  * @tag forge-overlay
  *
- * @summary Overlays are used to render content in an element that rendered above all content on the page,
- * and positioned around a specified anchor element.
+ * @summary Overlays are used to show content in an element that is rendered above all other content on the page, and positioned around a specified anchor element. This is a low-level building block component that does not provide any visual styles, but is used within other components such as popovers, and tooltips.
  *
  * @description
  * An overlay is a low-level building block component that does not provide any visual styles. Its only

package/esm/page-state/page-state.d.ts

@@ -14,7 +14,7 @@ declare global {
 /**
  * @tag forge-page-state
  *
- * @summary Page states display full-page messages for empty states, errors, or loading scenarios.
+ * @summary Page states display full-height messages for empty states, errors, or other general information. They can be used as full page content, or within smaller containers and will adapt accordingly.
  *
  * @cssproperty --forge-page-state-width - The width of the page state.
  * @cssproperty --forge-page-state-height - The height of the page state.

package/esm/page-state/page-state.js

@@ -12,7 +12,7 @@ const styles = ':host{--_page-state-width:var(--forge-page-state-width, 576px);-
 /**
  * @tag forge-page-state
  *
- * @summary Page states display full-page messages for empty states, errors, or loading scenarios.
+ * @summary Page states display full-height messages for empty states, errors, or other general information. They can be used as full page content, or within smaller containers and will adapt accordingly.
  *
  * @cssproperty --forge-page-state-width - The width of the page state.
  * @cssproperty --forge-page-state-height - The height of the page state.

package/esm/paginator/paginator-core.d.ts

@@ -18,6 +18,14 @@ export interface IPaginatorCore {
     alternative: boolean;
     rangeLabelCallback: PaginatorRangeLabelBuilder;
     focus(options?: FocusOptions): void;
+    goToFirstPage(): void;
+    goToPreviousPage(): void;
+    goToNextPage(): void;
+    goToLastPage(): void;
+    canGoToFirstPage(): boolean;
+    canGoToPreviousPage(): boolean;
+    canGoToNextPage(): boolean;
+    canGoToLastPage(): boolean;
 }
 export declare class PaginatorCore {
     private _adapter;
@@ -41,9 +49,13 @@ export declare class PaginatorCore {
     initialize(): void;
     focus(options?: FocusOptions): void;
     private _attachListeners;
+    goToFirstPage(): void;
     private _onFirstPage;
+    goToPreviousPage(): void;
     private _onPreviousPage;
+    goToNextPage(): void;
     private _onNextPage;
+    goToLastPage(): void;
     private _onLastPage;
     private _onPageSizeChanged;
     private _dispatchChangeEvent;
@@ -84,4 +96,8 @@ export declare class PaginatorCore {
     set alternative(value: boolean);
     get rangeLabelCallback(): PaginatorRangeLabelBuilder;
     set rangeLabelCallback(value: PaginatorRangeLabelBuilder);
+    canGoToFirstPage(): boolean;
+    canGoToPreviousPage(): boolean;
+    canGoToNextPage(): boolean;
+    canGoToLastPage(): boolean;
 }

package/esm/paginator/paginator-core.js

@@ -46,9 +46,7 @@ export class PaginatorCore {
         this._adapter.attachNextPageListener(this._nextPageListener);
         this._adapter.attachLastPageListener(this._lastPageListener);
     }
-    _onFirstPage(evt) {
-        evt.stopPropagation();
-        /* c8 ignore next 3 */
+    goToFirstPage() {
         if (!this._hasFirstPage()) {
             return;
         }
@@ -58,9 +56,11 @@ export class PaginatorCore {
             this._applyPageIndex(firstPage);
         }
     }
-    _onPreviousPage(evt) {
+    _onFirstPage(evt) {
         evt.stopPropagation();
-        /* c8 ignore next 3 */
+        this.goToFirstPage();
+    }
+    goToPreviousPage() {
         if (!this._hasPreviousPage()) {
             return;
         }
@@ -70,9 +70,11 @@ export class PaginatorCore {
             this._applyPageIndex(prevPage);
         }
     }
-    _onNextPage(evt) {
+    _onPreviousPage(evt) {
         evt.stopPropagation();
-        /* c8 ignore next 3 */
+        this.goToPreviousPage();
+    }
+    goToNextPage() {
         if (!this._hasNextPage()) {
             return;
         }
@@ -82,9 +84,11 @@ export class PaginatorCore {
             this._applyPageIndex(nextPage);
         }
     }
-    _onLastPage(evt) {
+    _onNextPage(evt) {
         evt.stopPropagation();
-        /* c8 ignore next 3 */
+        this.goToNextPage();
+    }
+    goToLastPage() {
         if (!this._hasLastPage()) {
             return;
         }
@@ -94,6 +98,10 @@ export class PaginatorCore {
             this._applyPageIndex(lastPage);
         }
     }
+    _onLastPage(evt) {
+        evt.stopPropagation();
+        this.goToLastPage();
+    }
     _onPageSizeChanged(evt) {
         evt.stopPropagation();
         const pageSize = Number(evt.detail);
@@ -384,4 +392,16 @@ export class PaginatorCore {
         this._rangeLabelCallback = value;
         this._updateRangeLabel();
     }
+    canGoToFirstPage() {
+        return this._hasFirstPage();
+    }
+    canGoToPreviousPage() {
+        return this._hasPreviousPage();
+    }
+    canGoToNextPage() {
+        return this._hasNextPage();
+    }
+    canGoToLastPage() {
+        return this._hasLastPage();
+    }
 }

package/esm/paginator/paginator.d.ts

@@ -17,6 +17,14 @@ export interface IPaginatorComponent extends IBaseComponent {
     disabled: boolean;
     alternative: boolean;
     rangeLabelCallback: PaginatorRangeLabelBuilder;
+    goToFirstPage(): void;
+    goToPreviousPage(): void;
+    goToNextPage(): void;
+    goToLastPage(): void;
+    canGoToFirstPage(): boolean;
+    canGoToPreviousPage(): boolean;
+    canGoToNextPage(): boolean;
+    canGoToLastPage(): boolean;
 }
 declare global {
     interface HTMLElementTagNameMap {
@@ -29,7 +37,7 @@ declare global {
 /**
  * @tag forge-paginator
  *
- * @summary Paginators provide navigation controls for dividing content across multiple pages.
+ * @summary Paginators provide navigation controls for dividing content across multiple pages. Typically used alongside data tables or lists.
  *
  * @slot label - Overrides the label text when in the default variant.
  * @slot range-label - Overrides the default range label with a custom label when in the default variant.
@@ -113,4 +121,32 @@ export declare class PaginatorComponent extends BaseComponent implements IPagina
     rangeLabelCallback: PaginatorRangeLabelBuilder;
     /** Sets focus to the first focusable element within the paginator. */
     focus(options?: FocusOptions): void;
+    /** Navigates to the first page. */
+    goToFirstPage(): void;
+    /** Navigates to the previous page. */
+    goToPreviousPage(): void;
+    /** Navigates to the next page. */
+    goToNextPage(): void;
+    /** Navigates to the last page. */
+    goToLastPage(): void;
+    /**
+     * Checks if navigation to the first page is possible.
+     * @returns True if can navigate to first page
+     */
+    canGoToFirstPage(): boolean;
+    /**
+     * Checks if navigation to the previous page is possible.
+     * @returns True if can navigate to previous page
+     */
+    canGoToPreviousPage(): boolean;
+    /**
+     * Checks if navigation to the next page is possible.
+     * @returns True if can navigate to next page
+     */
+    canGoToNextPage(): boolean;
+    /**
+     * Checks if navigation to the last page is possible.
+     * @returns True if can navigate to last page
+     */
+    canGoToLastPage(): boolean;
 }