@tylertech/forge 3.10.5 → 3.12.0

package/esm/list/list-item/list-item.d.ts

@@ -64,6 +64,7 @@ declare const ListItemComponent_base: import("../..").AbstractConstructor<import
  * @slot tertiary-text - The tertiary text.
  * @slot start - The start content.
  * @slot end - The end element.
+ * @slot additional-content - Additional content that appears below the main list item interactive area.
  *
  * @csspart root - The root container element.
  * @csspart text-container - The container for the text content.

package/esm/list/list-item/list-item.js

@@ -13,7 +13,7 @@ import { FocusIndicatorComponent } from '../../focus-indicator';
 import { WithElementInternals } from '../../core/mixins/internals/with-element-internals';
 import { WithDefaultAria } from '../../core/mixins/internals/with-default-aria';
 import { BaseComponent } from '../../core/base/base-component';
-const template = '<template><div class=\"forge-list-item\" part=\"root\"><slot name=\"start\"><slot name=\"leading\"></slot></slot><div class=\"text-container\" part=\"text-container\"><slot></slot><slot name=\"secondary-text\"></slot><slot name=\"tertiary-text\"></slot></div><slot name=\"end\"><slot name=\"trailing\"></slot></slot></div></template>';
+const template = '<template><div class=\"forge-list-item\" part=\"root\"><slot name=\"start\"><slot name=\"leading\"></slot></slot><div class=\"text-container\" part=\"text-container\"><slot></slot><slot name=\"secondary-text\"></slot><slot name=\"tertiary-text\"></slot></div><slot name=\"end\"><slot name=\"trailing\"></slot></slot></div><slot name=\"additional-content\"></slot></template>';
 const styles = ':host{--_list-item-indent:var(--forge-list-item-indent, var(--forge-spacing-xxlarge, 48px));--_list-item-dense-indent:var(--forge-list-item-dense-indent, var(--forge-spacing-xxlarge, 48px));--_list-item-disabled-cursor:var(--forge-list-item-disabled-cursor, not-allowed)}:host{display:block;outline:0}:host([hidden]){display:none}.forge-list-item{--_list-item-background:var(--forge-list-item-background, transparent);--_list-item-shape:var(--forge-list-item-shape, 0);--_list-item-padding:var(--forge-list-item-padding, 0 var(--forge-spacing-medium, 16px));--_list-item-margin:var(--forge-list-item-margin, 0);--_list-item-height:var(--forge-list-item-height, 48px);--_list-item-dense-height:var(--forge-list-item-dense-height, 32px);--_list-item-cursor:var(--forge-list-item-cursor, pointer);--_list-item-gap:var(--forge-list-item-gap, var(--forge-spacing-large, 24px));--_list-item-text-color:var(--forge-list-item-text-color, var(--forge-theme-text-medium, rgba(0, 0, 0, 0.6)));--_list-item-text-font-size:var(--forge-list-item-text-font-size, var(--forge-typography-body2-font-size, calc(var(--forge-typography-font-size, 1rem) * var(--forge-typography-body-font-size-scale, 1))));--_list-item-text-font-weight:var(--forge-list-item-text-font-weight, var(--forge-typography-body2-font-weight, 400));--_list-item-text-line-height:var(--forge-list-item-text-line-height, 1.5rem);--_list-item-selected-color:var(--forge-list-item-selected-color, var(--forge-theme-primary, #3f51b5));--_list-item-selected-background:var(--forge-list-item-selected-background, var(--_list-item-selected-color));--_list-item-selected-opacity:var(--forge-list-item-selected-opacity, 0.08);--_list-item-selected-start-color:var(--forge-list-item-selected-start-color, var(--_list-item-selected-color));--_list-item-selected-end-color:var(--forge-list-item-selected-end-color, var(--_list-item-selected-color));--_list-item-selected-text-color:var(--forge-list-item-selected-text-color, var(--forge-theme-text-medium, rgba(0, 0, 0, 0.6)));--_list-item-disabled-opacity:var(--forge-list-item-disabled-opacity, 0.38);--_list-item-one-line-height:var(--forge-list-item-one-line-height, var(--_list-item-height));--_list-item-two-line-height:var(--forge-list-item-two-line-height, var(--forge-list-item-height, 72px));--_list-item-three-line-height:var(--forge-list-item-three-line-height, var(--forge-list-item-height, 88px));--_list-item-dense-one-line-height:var(--forge-list-item-dense-one-line-height, var(--_list-item-dense-height));--_list-item-dense-two-line-height:var(--forge-list-item-dense-two-line-height, var(--forge-list-item-dense-height, 56px));--_list-item-dense-three-line-height:var(--forge-list-item-dense-three-line-height, var(--forge-list-item-dense-height, 72px));--_list-item-dense-font-size:var(--forge-list-item-dense-font-size, 0.875rem);--_list-item-dense-gap:var(--forge-list-item-dense-gap, var(--forge-spacing-xsmall, 8px));--_list-item-start-selected-color:var(--forge-list-item-start-selected-color, var(--_list-item-selected-color));--_list-item-end-selected-color:var(--forge-list-item-end-selected-color, var(--_list-item-selected-color));--_list-item-wrap-padding:var(--forge-list-item-wrap-padding, var(--forge-spacing-xsmall, 8px) var(--forge-spacing-medium, 16px))}.forge-list-item{position:relative;display:flex;gap:var(--_list-item-gap);align-items:center;box-sizing:border-box;outline:0;text-decoration:none;border-radius:var(--_list-item-shape);-webkit-tap-highlight-color:transparent;background-color:var(--_list-item-background);height:var(--_list-item-height);min-height:var(--_list-item-height);padding:var(--_list-item-padding);margin:var(--_list-item-margin)}.forge-list-item.interactive{cursor:var(--_list-item-cursor)}.forge-list-item.disabled{cursor:var(--_list-item-disabled-cursor);opacity:var(--_list-item-disabled-opacity)}.forge-list-item.disabled ::slotted(button){cursor:var(--_list-item-disabled-cursor)}.anchor{position:absolute;inset:0}:host([two-line]) .forge-list-item{height:var(--_list-item-two-line-height);min-height:var(--_list-item-two-line-height)}:host([three-line]) .forge-list-item{height:var(--_list-item-three-line-height);min-height:var(--_list-item-three-line-height)}:host([dense]) .forge-list-item{--_list-item-gap:var(--_list-item-dense-gap);height:var(--_list-item-dense-one-line-height);min-height:var(--_list-item-dense-one-line-height)}:host([dense]) .text-container{font-size:var(--_list-item-dense-font-size)}:host([dense][indented]){margin-inline-start:var(--_list-item-dense-indent)}:host([dense][two-line]) .forge-list-item{height:var(--_list-item-dense-two-line-height);min-height:var(--_list-item-dense-two-line-height)}:host([dense][three-line]) .forge-list-item{height:var(--_list-item-dense-three-line-height);min-height:var(--_list-item-dense-three-line-height)}:host([selected]) .forge-list-item{color:var(--_list-item-selected-color)}:host([selected]) .forge-list-item::before{content:\"\";position:absolute;inset:0;border-radius:inherit;opacity:var(--_list-item-selected-opacity);background-color:var(--_list-item-selected-background);pointer-events:none}:host([selected]) .forge-list-item ::slotted([slot=end]),:host([selected]) .forge-list-item ::slotted([slot=leading]),:host([selected]) .forge-list-item ::slotted([slot=start]),:host([selected]) .forge-list-item ::slotted([slot=trailing]){color:var(--_list-item-selected-color);isolation:isolate}:host([selected]) .forge-list-item ::slotted([slot=leading]),:host([selected]) .forge-list-item ::slotted([slot=start]){color:var(--_list-item-start-selected-color)}:host([selected]) .forge-list-item ::slotted([slot=end]),:host([selected]) .forge-list-item ::slotted([slot=trailing]){color:var(--_list-item-end-selected-color)}:host([selected]) .text-container{color:var(--_list-item-selected-color)}:host([selected]) forge-state-layer{--forge-state-layer-color:var(--_list-item-selected-color)}:host([indented]) .forge-list-item{margin-inline-start:var(--_list-item-indent)}.text-container{-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased;font-family:var(--forge-typography-body2-font-family, var(--forge-typography-font-family, \"Roboto\", sans-serif));letter-spacing:var(--forge-typography-body2-letter-spacing, .015625em);text-transform:var(--forge-typography-body2-text-transform,inherit);text-decoration:var(--forge-typography-body2-text-decoration,inherit);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;box-sizing:border-box;isolation:isolate;font-size:var(--_list-item-text-font-size);font-weight:var(--_list-item-text-font-weight);line-height:var(--_list-item-text-line-height);flex:1;contain:layout}slot[name=secondary-text]::slotted(*),slot[name=tertiary-text]::slotted(*){-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased;font-family:var(--forge-typography-body1-font-family, var(--forge-typography-font-family, \"Roboto\", sans-serif));font-size:var(--forge-typography-body1-font-size, calc(var(--forge-typography-font-size, 1rem) * var(--forge-typography-body-font-size-scale, .875)));font-weight:var(--forge-typography-body1-font-weight,400);line-height:var(--forge-typography-body1-line-height, calc(var(--forge-typography-font-size, 1rem) * var(--forge-typography-body-line-height-scale, 1.125)));letter-spacing:var(--forge-typography-body1-letter-spacing, .0357142857em);text-transform:var(--forge-typography-body1-text-transform,inherit);text-decoration:var(--forge-typography-body1-text-decoration,inherit);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;color:var(--_list-item-text-color);display:block}:host([selected]) slot[name=secondary-text]::slotted(*),:host([selected]) slot[name=tertiary-text]::slotted(*){color:var(--_list-item-selected-text-color)}::slotted(:is(button:not([slot]),[forge-list-item-button])){appearance:none;cursor:var(--_list-item-cursor);border:none;padding-block:0;padding-inline:0;margin:0;box-sizing:border-box;width:100%;background:0 0;color:inherit;outline:0;font:inherit;user-select:auto;text-align:inherit;letter-spacing:inherit;word-spacing:inherit;white-space:nowrap;text-overflow:ellipsis;overflow:hidden;display:block}::slotted(a){outline:0;color:inherit!important;text-decoration:none!important}::slotted([slot=end]),::slotted([slot=leading]),::slotted([slot=start]),::slotted([slot=trailing]){color:var(--_list-item-text-color);display:inline-flex;flex-shrink:0;align-items:center;justify-content:center;fill:currentColor}:host(:not([noninteractive])) ::slotted(:is(forge-checkbox,forge-radio,forge-switch):is([slot=start],[slot=end],[slot=leading],[slot=trailing]):not([forge-ignore])){--forge-focus-indicator-display:none;--forge-state-layer-display:none}:host([selected]) ::slotted([slot=leading]),:host([selected]) ::slotted([slot=start]){color:var(--_list-item-start-selected-color)}:host([selected]) ::slotted([slot=end]),:host([selected]) ::slotted([slot=trailing]){color:var(--_list-item-end-selected-color)}:host([wrap]) .forge-list-item{--_list-item-padding:var(--_list-item-wrap-padding);height:auto}:host([wrap]) .text-container{white-space:normal;overflow:visible;text-overflow:clip;line-height:normal}:host([wrap]) ::slotted(:is(button,[role=button][tabindex],[forge-list-item-button])){white-space:normal}:host([wrap]) slot[name=secondary-text]::slotted(*),:host([wrap]) slot[name=tertiary-text]::slotted(*){white-space:normal;overflow:visible;text-overflow:clip;line-height:normal}forge-focus-indicator{z-index:1;--forge-focus-indicator-shape:calc(var(--forge-shape-medium, 4px) * var(--forge-shape-factor, 1))}forge-state-layer{border-radius:inherit}';
 /**
  * @tag forge-list-item
@@ -49,6 +49,7 @@ const styles = ':host{--_list-item-indent:var(--forge-list-item-indent, var(--fo
  * @slot tertiary-text - The tertiary text.
  * @slot start - The start content.
  * @slot end - The end element.
+ * @slot additional-content - Additional content that appears below the main list item interactive area.
  *
  * @csspart root - The root container element.
  * @csspart text-container - The container for the text content.

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

@@ -7,6 +7,7 @@ import type { IIconComponent } from '../icon';
 import type { IOverlayOffset, OverlayFlipState, OverlayShiftState } from '../overlay/overlay-constants';
 import { PositionPlacement } from '../core/utils/position-utils';
 import { TooltipPlacement, TooltipType } from '../tooltip';
+import type { PopoverAnchorAccessibility } from '../popover/popover-constants';
 export declare const LIST_DROPDOWN_CONSTANTS: {
     observedAttributes: {
         POPUP_CLASSES: string;
@@ -39,12 +40,16 @@ export declare const LIST_DROPDOWN_CONSTANTS: {
     classes: {
         GROUP_WRAPPER: string;
     };
+    selectAllOption: {
+        VALUE: string;
+        LABEL: string;
+    };
 };
 export type ListDropdownOptionBuilder<T = HTMLElement> = (option: IListDropdownOption, parentElement: T) => HTMLElement | string | void;
 export type ListDropdownHeaderBuilder = () => HTMLElement;
 export type ListDropdownFooterBuilder = () => HTMLElement;
 export type ListDropdownOptionGroupBuilder<T = any> = (option: IListDropdownOptionGroup<T>) => HTMLElement | string;
-export type ListDropdownTransformCallback = (label: string) => string | HTMLElement;
+export type ListDropdownTransformCallback = (label: string, option?: IListDropdownOption, isSelected?: boolean) => string | HTMLElement;
 export type ListDropdownIconType = 'font' | 'component';
 export interface IBaseListDropdownOption<T = any> {
     value: T;
@@ -84,6 +89,8 @@ export interface IListDropdownConfig<T = any> {
     options: Array<IListDropdownOption | IListDropdownOptionGroup>;
     selectCallback: (value: T) => void;
     activeChangeCallback?: (id: string) => void;
+    showSelectAll?: boolean;
+    selectAllLabel?: string;
     closeCallback?: () => void;
     syncWidth?: boolean;
     constrainViewportWidth?: boolean;
@@ -115,6 +122,7 @@ export interface IListDropdownConfig<T = any> {
     footerBuilder?: ListDropdownFooterBuilder;
     cascade?: boolean;
     cascadingElementFactory?: (config: IListDropdownCascadingElementFactoryConfig) => HTMLElement;
+    anchorAccessibility?: PopoverAnchorAccessibility;
 }
 export interface IListDropdownCascadingElementFactoryConfig {
     index: number;
@@ -141,4 +149,6 @@ export interface ListDropdownTooltipConfig {
     offset?: number;
     anchor?: string;
     anchorElement?: HTMLElement;
+    visibilityMode?: ListDropdownTooltipVisibilityMode;
 }
+export type ListDropdownTooltipVisibilityMode = 'always' | 'overflow-only';

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

@@ -25,10 +25,15 @@ const attributes = {
 const classes = {
     GROUP_WRAPPER: 'forge-list-dropdown__group-wrapper'
 };
+const selectAllOption = {
+    VALUE: '__forge_select_all__',
+    LABEL: 'Select All'
+};
 export const LIST_DROPDOWN_CONSTANTS = {
     observedAttributes,
     attributes,
-    classes
+    classes,
+    selectAllOption
 };
 export const DEFAULT_LIST_DROPDOWN_CONFIG = {
     options: [],

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';
@@ -97,8 +101,35 @@ export function createList(config) {
  * @param config
  */
 export function createListItems(config, listElement, options, startIndex = 0, renderSelected = true) {
+    // Add select all option if enabled and in multiple mode
+    let optionsToRender = options || config.options;
+    if (config.showSelectAll && config.multiple && startIndex === 0) {
+        const selectAllOption = {
+            value: LIST_DROPDOWN_CONSTANTS.selectAllOption.VALUE,
+            label: config.selectAllLabel || LIST_DROPDOWN_CONSTANTS.selectAllOption.LABEL
+        };
+        const dividerOption = {
+            value: '',
+            label: '',
+            divider: true
+        };
+        // Inject select all at the beginning
+        if (isListDropdownOptionType(optionsToRender, ListDropdownOptionType.Group)) {
+            const optionGroups = optionsToRender;
+            if (optionGroups.length > 0) {
+                optionGroups[0] = { ...optionGroups[0], options: [selectAllOption, dividerOption, ...optionGroups[0].options] };
+                optionsToRender = optionGroups;
+            }
+            else {
+                optionsToRender = [{ text: '', options: [selectAllOption, dividerOption] }];
+            }
+        }
+        else {
+            optionsToRender = [selectAllOption, dividerOption, ...optionsToRender];
+        }
+    }
     // Ensure the options are provided in the form a group (if no groups provided, then we have one anonymous group of options)
-    const groups = getOptionsByGroup(options || config.options);
+    const groups = getOptionsByGroup(optionsToRender);
     const flatOptions = getFlattenedOptions(groups);
     const limitOptions = config.optionLimit ? true : false;
     let optionLimit = config.optionLimit || 0;
@@ -193,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;
                     }
@@ -202,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`;
@@ -230,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);
@@ -303,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 > listItemElement.clientWidth || secondaryLabelElement.scrollWidth > listItemElement.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/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,8 +39,15 @@ declare global {
 /**
  * @tag forge-menu
  *
+ * @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[];
@@ -117,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,8 +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. 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() {
@@ -38,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() {
@@ -82,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() {
@@ -139,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

@@ -12,9 +12,10 @@ declare global {
     }
 }
 /**
- *
  * @tag forge-page-state
  *
+ * @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.
  * @cssproperty --forge-page-state-spacing - The spacing of the page state.

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

@@ -10,9 +10,10 @@ import { PAGE_STATE_CONSTANTS } from './page-state-constants';
 const template = '<template><div class=\"forge-page-state\" part=\"root\"><div class=\"graphic\" part=\"graphic-container\"><slot name=\"graphic\"></slot></div><div class=\"title\" part=\"title-container\"><slot name=\"title\"></slot></div><div class=\"message\" part=\"message-container\"><slot name=\"message\"></slot></div><div class=\"actions\" part=\"actions-container\"><slot name=\"action\"></slot></div></div></template>';
 const styles = ':host{--_page-state-width:var(--forge-page-state-width, 576px);--_page-state-height:var(--forge-page-state-height, auto);--_page-state-spacing:var(--forge-page-state-spacing, var(--forge-spacing-xxxlarge, 56px));--_page-state-mobile-width:var(--forge-page-state-mobile-width, 70%);--_page-state-graphic-height:var(--forge-page-state-graphic-height, 296px);--_page-state-graphic-spacing:var(--forge-page-state-graphic-spacing, var(--forge-spacing-xxxlarge, 56px));--_page-state-mobile-graphic-height:var(--forge-page-state-mobile-graphic-height, auto);--_page-state-title-color:var(--forge-page-state-title-color, var(--forge-theme-text-medium, rgba(0, 0, 0, 0.6)));--_page-state-title-spacing:var(--forge-page-state-title-spacing, var(--forge-spacing-xxxlarge, 56px));--_page-state-title-spacing-mobile:var(--forge-page-state-title-spacing-mobile, var(--forge-spacing-large, 24px));--_page-state-message-color:var(--forge-page-state-message-color, var(--forge-theme-text-high, rgba(0, 0, 0, 0.87)));--_page-state-message-spacing:var(--forge-page-state-message-spacing, var(--forge-spacing-xxxlarge, 56px));--_page-state-message-spacing-mobile:var(--forge-page-state-message-spacing-mobile, var(--forge-spacing-large, 24px));--_page-state-actions-spacing:var(--forge-page-state-actions-spacing, 16px)}:host{display:flex;justify-content:center;align-items:center;width:100%;container-type:inline-size}:host([hidden]){display:none}.forge-page-state{width:var(--_page-state-width);margin-block:var(--_page-state-spacing);text-align:center}.forge-page-state .graphic{display:flex;justify-content:center;align-items:center;height:var(--_page-state-graphic-height);width:100%;margin-block-end:var(--_page-state-graphic-spacing)}.forge-page-state .graphic ::slotted([slot=graphic]){height:100%;width:100%}.forge-page-state .title{-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased;font-family:var(--forge-typography-heading8-font-family, var(--forge-typography-font-family, \"Roboto\", sans-serif));font-size:var(--forge-typography-heading8-font-size, calc(var(--forge-typography-font-size, 1rem) * var(--forge-typography-heading8-font-size-scale, 2.25)));font-weight:var(--forge-typography-heading8-font-weight,500);line-height:var(--forge-typography-heading8-line-height, calc(var(--forge-typography-font-size, 1rem) * var(--forge-typography-heading8-line-height-scale, 2.625)));letter-spacing:var(--forge-typography-heading8-letter-spacing, -.0027777778em);text-transform:var(--forge-typography-heading8-text-transform,inherit);text-decoration:var(--forge-typography-heading8-text-decoration,inherit);--_page-state-title-spacing:var(--_page-state-title-spacing-mobile);color:var(--_page-state-title-color);margin-block:var(--_page-state-title-spacing)}.forge-page-state .message{-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased;font-family:var(--forge-typography-body4-font-family, var(--forge-typography-font-family, \"Roboto\", sans-serif));font-size:var(--forge-typography-body4-font-size, calc(var(--forge-typography-font-size, 1rem) * var(--forge-typography-body-font-size-scale, 1.25)));font-weight:var(--forge-typography-body4-font-weight,400);line-height:var(--forge-typography-body4-line-height, calc(var(--forge-typography-font-size, 1rem) * var(--forge-typography-body-line-height-scale, 1.75)));letter-spacing:var(--forge-typography-body4-letter-spacing, .005em);text-transform:var(--forge-typography-body4-text-transform,inherit);text-decoration:var(--forge-typography-body4-text-decoration,inherit);--_page-state-message-spacing:var(--_page-state-message-spacing-mobile);color:var(--_page-state-message-color);margin-block-end:var(--_page-state-message-spacing)}.forge-page-state .actions{display:grid;justify-content:center;grid-auto-flow:column;gap:var(--_page-state-actions-spacing)}@container (max-width:599px){.forge-page-state{--_page-state-width:var(--_page-state-mobile-width)}.forge-page-state .graphic{--_page-state-graphic-height:var(--_page-state-mobile-graphic-height);--_page-state-graphic-spacing:var(--forge-page-state-graphic-spacing, 0)}.forge-page-state .title{-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased;font-family:var(--forge-typography-heading5-font-family, var(--forge-typography-font-family, \"Roboto\", sans-serif));font-size:var(--forge-typography-heading5-font-size, calc(var(--forge-typography-font-size, 1rem) * var(--forge-typography-heading5-font-size-scale, 1.5)));font-weight:var(--forge-typography-heading5-font-weight,500);line-height:var(--forge-typography-heading5-line-height, calc(var(--forge-typography-font-size, 1rem) * var(--forge-typography-heading5-line-height-scale, 1.75)));letter-spacing:var(--forge-typography-heading5-letter-spacing, 0);text-transform:var(--forge-typography-heading5-text-transform,inherit);text-decoration:var(--forge-typography-heading5-text-decoration,inherit)}.forge-page-state .message{-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased;font-family:var(--forge-typography-body2-font-family, var(--forge-typography-font-family, \"Roboto\", sans-serif));font-size:var(--forge-typography-body2-font-size, calc(var(--forge-typography-font-size, 1rem) * var(--forge-typography-body-font-size-scale, 1)));font-weight:var(--forge-typography-body2-font-weight,400);line-height:var(--forge-typography-body2-line-height, calc(var(--forge-typography-font-size, 1rem) * var(--forge-typography-body-line-height-scale, 1.375)));letter-spacing:var(--forge-typography-body2-letter-spacing, .015625em);text-transform:var(--forge-typography-body2-text-transform,inherit);text-decoration:var(--forge-typography-body2-text-decoration,inherit)}.forge-page-state .actions{grid-auto-flow:row}}';
 /**
- *
  * @tag forge-page-state
  *
+ * @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.
  * @cssproperty --forge-page-state-spacing - The spacing of the page state.