@fluentui/priority-overflow 9.3.0 → 9.4.0

package/CHANGELOG.md

@@ -1,12 +1,26 @@
 # Change Log - @fluentui/priority-overflow
 
-This log was last generated on Thu, 12 Feb 2026 10:42:45 GMT and should not be manually modified.
+This log was last generated on Wed, 24 Jun 2026 11:03:53 GMT and should not be manually modified.
 
 <!-- Start content -->
 
+## [9.4.0](https://github.com/microsoft/fluentui/tree/@fluentui/priority-overflow_v9.4.0)
+
+Wed, 24 Jun 2026 11:03:53 GMT 
+[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/priority-overflow_v9.3.0..@fluentui/priority-overflow_v9.4.0)
+
+### Minor changes
+
+- feat: createOverflowManager accepts initialOptions, new setOptions method, observe now returns its cleanup, and the OverflowManagerOptions type is exported. ([PR #36262](https://github.com/microsoft/fluentui/pull/36262) by bsunderhus@microsoft.com)
+- feat: expose getSnapshot and subscribe on OverflowManager ([PR #36263](https://github.com/microsoft/fluentui/pull/36263) by bsunderhus@microsoft.com)
+
+### Patches
+
+- fix: recompute overflow eagerly when the overflow menu attaches or detaches ([PR #36264](https://github.com/microsoft/fluentui/pull/36264) by bsunderhus@microsoft.com)
+
 ## [9.3.0](https://github.com/microsoft/fluentui/tree/@fluentui/priority-overflow_v9.3.0)
 
-Thu, 12 Feb 2026 10:42:45 GMT 
+Thu, 12 Feb 2026 10:46:12 GMT 
 [Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/priority-overflow_v9.2.1..@fluentui/priority-overflow_v9.3.0)
 
 ### Minor changes

package/dist/index.d.ts

@@ -1,67 +1,71 @@
 /**
+ * Creates an overflow manager instance for a single container.
+ *
  * @internal
+ * @param initialOptions - Initial observe options. Missing values are filled with defaults.
  * @returns overflow manager instance
  */
-export declare function createOverflowManager(): OverflowManager;
+export declare function createOverflowManager(initialOptions?: Partial<OverflowOptions>): OverflowManager;
 
-export declare interface ObserveOptions {
-    /**
-     * Padding (in px) at the end of the container before overflow occurs
-     * Useful to account for extra elements (i.e. dropdown menu)
-     * or to account for any kinds of margins between items which are hard to measure with JS
-     * @default 10
-     */
-    padding?: number;
-    /**
-     * Direction where items are removed when overflow occurs
-     * @default end
-     */
-    overflowDirection?: OverflowDirection;
-    /**
-     * Horizontal or vertical overflow
-     * @default horizontal
-     */
-    overflowAxis?: OverflowAxis;
-    /**
-     * The minimum number of visible items
-     */
-    minimumVisible?: number;
-    /**
-     * Callback when item visibility is updated
-     */
-    onUpdateItemVisibility: OnUpdateItemVisibility;
-    /**
-     * Callback when item visibility is updated
-     */
-    onUpdateOverflow: OnUpdateOverflow;
+/**
+ * An empty, frozen overflow snapshot used as the default before anything has been measured.
+ * @internal
+ */
+export declare const EMPTY_SNAPSHOT: OverflowSnapshot;
+
+export declare interface ObserveOptions extends Partial<OverflowOptions> {
     /**
-     * When true, the overflow menu has default hidden items
+     * forces update when observation begins, ensuring initial overflow state is correct. This is useful when the container starts with items that should be overflowed, or when the container resizes immediately after mounting.
      * @default false
      */
-    hasHiddenItems?: boolean;
+    forceUpdate?: boolean;
 }
 
+/**
+ * Callback invoked when a single item's visibility changes.
+ */
 export declare type OnUpdateItemVisibility = (data: OnUpdateItemVisibilityPayload) => void;
 
+/**
+ * Payload for item-level visibility updates.
+ */
 export declare interface OnUpdateItemVisibilityPayload {
+    /**
+     * Item whose visibility changed.
+     */
     item: OverflowItemEntry;
+    /**
+     * Whether the item is now visible.
+     */
     visible: boolean;
 }
 
 /**
- * signature similar to standard event listeners, but typed to handle the custom event
+ * Signature similar to standard event listeners, typed for overflow updates.
  */
 export declare type OnUpdateOverflow = (data: OverflowEventPayload) => void;
 
+/**
+ * Axis used to measure overflow.
+ */
 export declare type OverflowAxis = 'horizontal' | 'vertical';
 
+/**
+ * Direction where items are removed when overflow occurs.
+ */
 export declare type OverflowDirection = 'start' | 'end';
 
+/**
+ * Tracked divider in the overflow manager.
+ */
 export declare interface OverflowDividerEntry {
     /**
-     * HTML element that will disappear when overflowed
+     * HTML element that disappears when its group overflows.
      */
     element: HTMLElement;
+    /**
+     * Id of the group controlled by this divider.
+     */
     groupId: string;
 }
 
@@ -69,27 +73,45 @@ export declare interface OverflowDividerEntry {
  * Payload of the custom DOM event for overflow updates
  */
 export declare interface OverflowEventPayload {
+    /**
+     * Items currently visible in the container.
+     */
     visibleItems: OverflowItemEntry[];
+    /**
+     * Items currently moved to overflow.
+     */
     invisibleItems: OverflowItemEntry[];
+    /**
+     * Current visibility state by group id.
+     */
     groupVisibility: Record<string, OverflowGroupState>;
 }
 
+/**
+ * Visibility state for an overflow group.
+ */
 export declare type OverflowGroupState = 'visible' | 'hidden' | 'overflow';
 
+/**
+ * Tracked item in the overflow manager.
+ */
 export declare interface OverflowItemEntry {
     /**
-     * HTML element that will be disappear when overflowed
+     * HTML element that disappears when the item overflows.
      */
     element: HTMLElement;
     /**
-     * Lower priority items are invisible first when the container is overflowed
+     * Lower-priority items become invisible first when the container overflows.
      * @default 0
      */
     priority: number;
     /**
-     * Specific id, used to track visibility and provide updates to consumers
+     * Stable item id used to track visibility and emit updates.
      */
     id: string;
+    /**
+     * Optional group id used to coordinate divider and grouped visibility states.
+     */
     groupId?: string;
     /**
      * If true, the item will never overflow and will always be visible.
@@ -100,17 +122,23 @@ export declare interface OverflowItemEntry {
 }
 
 /**
+ * Internal manager contract used to observe and compute priority overflow.
+ *
  * @internal
  */
 export declare interface OverflowManager {
     /**
      * Starts observing the container and managing the overflow state
      */
-    observe: (container: HTMLElement, options: ObserveOptions) => void;
+    observe: (container: HTMLElement, options?: ObserveOptions) => void;
     /**
      * Stops observing the container
      */
     disconnect: () => void;
+    /**
+     * Updates engine options without restarting observation.
+     */
+    setOptions: (options: Partial<OverflowOptions>) => void;
     /**
      * Add overflow items
      */
@@ -144,6 +172,75 @@ export declare interface OverflowManager {
      * Unsets the overflow menu element
      */
     removeOverflowMenu: () => void;
+    /**
+     * Returns the current overflow snapshot.
+     */
+    getSnapshot: () => OverflowSnapshot;
+    /**
+     * Subscribes to snapshot changes.
+     */
+    subscribe: (listener: () => void) => () => void;
+}
+
+/**
+ * Options used to initialize or reconfigure overflow observation.
+ */
+export declare interface OverflowOptions {
+    /**
+     * Padding in pixels reserved at the end of the container before overflow occurs.
+     * Useful for accounting for extra elements (for example an overflow menu button)
+     * or margins between items that are difficult to measure in JavaScript.
+     * @default 10
+     */
+    padding?: number;
+    /**
+     * Direction where items are removed when overflow occurs.
+     * @default end
+     */
+    overflowDirection?: OverflowDirection;
+    /**
+     * Overflow axis used for size measurement.
+     * @default horizontal
+     */
+    overflowAxis?: OverflowAxis;
+    /**
+     * Minimum number of items that must remain visible.
+     */
+    minimumVisible?: number;
+    /**
+     * Callback invoked when an individual item's visibility changes.
+     */
+    onUpdateItemVisibility: OnUpdateItemVisibility;
+    /**
+     * Callback invoked after overflow state is recomputed.
+     */
+    onUpdateOverflow: OnUpdateOverflow;
+    /**
+     * When true, reserve space as if the overflow menu were visible even with no overflowing items.
+     * @default false
+     */
+    hasHiddenItems?: boolean;
+}
+
+/**
+ * Indexed, immutable overflow state returned by `OverflowManager.getSnapshot`.
+ *
+ * Unlike {@link OverflowEventPayload}, this is shaped for O(1) consumer lookups (item/group
+ * visibility by id, item count) rather than ordered item entries.
+ */
+export declare interface OverflowSnapshot {
+    /**
+     * Visibility of each registered item, keyed by item id.
+     */
+    itemVisibility: Record<string, boolean>;
+    /**
+     * Current visibility state by group id.
+     */
+    groupVisibility: Record<string, OverflowGroupState>;
+    /**
+     * Number of items currently moved to overflow (invisible).
+     */
+    invisibleItemCount: number;
 }
 
 export { }

package/lib/consts.js

@@ -1,2 +1,10 @@
 export const DATA_OVERFLOWING = 'data-overflowing';
 export const DATA_OVERFLOW_GROUP = 'data-overflow-group';
+/**
+ * An empty, frozen overflow snapshot used as the default before anything has been measured.
+ * @internal
+ */ export const EMPTY_SNAPSHOT = Object.freeze({
+    itemVisibility: {},
+    groupVisibility: {},
+    invisibleItemCount: 0
+});

package/lib/consts.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/consts.ts"],"sourcesContent":["export const DATA_OVERFLOWING = 'data-overflowing';\nexport const DATA_OVERFLOW_GROUP = 'data-overflow-group';\n"],"names":["DATA_OVERFLOWING","DATA_OVERFLOW_GROUP"],"mappings":"AAAA,OAAO,MAAMA,mBAAmB,mBAAmB;AACnD,OAAO,MAAMC,sBAAsB,sBAAsB"}
+{"version":3,"sources":["../src/consts.ts"],"sourcesContent":["import type { OverflowSnapshot } from './types';\n\nexport const DATA_OVERFLOWING = 'data-overflowing';\nexport const DATA_OVERFLOW_GROUP = 'data-overflow-group';\n\n/**\n * An empty, frozen overflow snapshot used as the default before anything has been measured.\n * @internal\n */\nexport const EMPTY_SNAPSHOT: OverflowSnapshot = Object.freeze({\n  itemVisibility: {},\n  groupVisibility: {},\n  invisibleItemCount: 0,\n});\n"],"names":["DATA_OVERFLOWING","DATA_OVERFLOW_GROUP","EMPTY_SNAPSHOT","Object","freeze","itemVisibility","groupVisibility","invisibleItemCount"],"mappings":"AAEA,OAAO,MAAMA,mBAAmB,mBAAmB;AACnD,OAAO,MAAMC,sBAAsB,sBAAsB;AAEzD;;;CAGC,GACD,OAAO,MAAMC,iBAAmCC,OAAOC,MAAM,CAAC;IAC5DC,gBAAgB,CAAC;IACjBC,iBAAiB,CAAC;IAClBC,oBAAoB;AACtB,GAAG"}

package/lib/index.js

@@ -1 +1,2 @@
 export { createOverflowManager } from './overflowManager';
+export { EMPTY_SNAPSHOT } from './consts';

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export { createOverflowManager } from './overflowManager';\nexport type {\n  ObserveOptions,\n  OnUpdateItemVisibility,\n  OnUpdateItemVisibilityPayload,\n  OnUpdateOverflow,\n  OverflowAxis,\n  OverflowDirection,\n  OverflowEventPayload,\n  OverflowGroupState,\n  OverflowItemEntry,\n  OverflowDividerEntry,\n  OverflowManager,\n} from './types';\n"],"names":["createOverflowManager"],"mappings":"AAAA,SAASA,qBAAqB,QAAQ,oBAAoB"}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export { createOverflowManager } from './overflowManager';\nexport { EMPTY_SNAPSHOT } from './consts';\nexport type {\n  ObserveOptions,\n  OverflowOptions,\n  OnUpdateItemVisibility,\n  OnUpdateItemVisibilityPayload,\n  OnUpdateOverflow,\n  OverflowAxis,\n  OverflowDirection,\n  OverflowEventPayload,\n  OverflowGroupState,\n  OverflowItemEntry,\n  OverflowDividerEntry,\n  OverflowManager,\n  OverflowSnapshot,\n} from './types';\n"],"names":["createOverflowManager","EMPTY_SNAPSHOT"],"mappings":"AAAA,SAASA,qBAAqB,QAAQ,oBAAoB;AAC1D,SAASC,cAAc,QAAQ,WAAW"}

package/lib/overflowManager.js

@@ -1,11 +1,25 @@
-import { DATA_OVERFLOWING, DATA_OVERFLOW_GROUP } from './consts';
+import { DATA_OVERFLOWING, DATA_OVERFLOW_GROUP, EMPTY_SNAPSHOT } from './consts';
 import { observeResize } from './createResizeObserver';
 import { debounce } from './debounce';
 import { createPriorityQueue } from './priorityQueue';
+const DEFAULT_OPTIONS = {
+    overflowAxis: 'horizontal',
+    overflowDirection: 'end',
+    padding: 10,
+    minimumVisible: 0,
+    hasHiddenItems: false,
+    onUpdateItemVisibility: ()=>{
+    /* noop */ },
+    onUpdateOverflow: ()=>{
+    /* noop */ }
+};
 /**
+ * Creates an overflow manager instance for a single container.
+ *
  * @internal
+ * @param initialOptions - Initial observe options. Missing values are filled with defaults.
  * @returns overflow manager instance
- */ export function createOverflowManager() {
+ */ export function createOverflowManager(initialOptions = {}) {
     // calls to `offsetWidth or offsetHeight` can happen multiple times in an update
     // Use a cache to avoid causing too many recalcs and avoid scripting time to meausure sizes
     const sizeCache = new Map();
@@ -17,17 +31,19 @@ import { createPriorityQueue } from './priorityQueue';
     // Initially true to force dispatch on first mount
     let forceDispatch = true;
     const options = {
-        padding: 10,
-        overflowAxis: 'horizontal',
-        overflowDirection: 'end',
-        minimumVisible: 0,
-        onUpdateItemVisibility: ()=>undefined,
-        onUpdateOverflow: ()=>undefined,
-        hasHiddenItems: false
+        ...DEFAULT_OPTIONS,
+        ...initialOptions
     };
     const overflowItems = {};
     const overflowDividers = {};
-    let disposeResizeObserver = ()=>null;
+    const listeners = new Set();
+    let disposeResizeObserver = ()=>{
+    /* noop */ };
+    let snapshot = EMPTY_SNAPSHOT;
+    const takeSnapshot = (nextSnapshot)=>{
+        snapshot = nextSnapshot;
+        listeners.forEach((listener)=>listener());
+    };
     const getNextItem = (queueToDequeue, queueToEnqueue)=>{
         const nextItem = queueToDequeue.dequeue();
         queueToEnqueue.enqueue(nextItem);
@@ -68,7 +84,10 @@ import { createPriorityQueue } from './priorityQueue';
     const invisibleItemQueue = createPriorityQueue((a, b)=>-1 * compareItems(a, b));
     const visibleItemQueue = createPriorityQueue(compareItems);
     function occupiedSize() {
-        const totalItemSize = visibleItemQueue.all().map((id)=>overflowItems[id].element).map(getOffsetSize).reduce((prev, current)=>prev + current, 0);
+        let totalItemSize = 0;
+        for (const id of visibleItemQueue){
+            totalItemSize += getOffsetSize(overflowItems[id].element);
+        }
         const totalDividerSize = Object.entries(groupManager.groupVisibility()).reduce((acc, [id, state])=>acc + (state !== 'hidden' && overflowDividers[id] ? getOffsetSize(overflowDividers[id].element) : 0), 0);
         const overflowMenuSize = (invisibleItemQueue.size() > 0 || options.hasHiddenItems) && overflowMenu ? getOffsetSize(overflowMenu) : 0;
         return totalItemSize + totalDividerSize + overflowMenuSize;
@@ -102,16 +121,35 @@ import { createPriorityQueue } from './priorityQueue';
         }
     };
     const dispatchOverflowUpdate = ()=>{
-        const visibleItemIds = visibleItemQueue.all();
-        const invisibleItemIds = invisibleItemQueue.all();
-        const visibleItems = visibleItemIds.map((itemId)=>overflowItems[itemId]);
-        const invisibleItems = invisibleItemIds.map((itemId)=>overflowItems[itemId]);
+        const groupVisibility = groupManager.groupVisibility();
+        // Build the legacy ordered-entry arrays and the snapshot's id -> visible map in a single pass
+        // over each queue.
+        const itemVisibility = {};
+        const visibleItems = [];
+        const invisibleItems = [];
+        for (const itemId of visibleItemQueue){
+            itemVisibility[itemId] = true;
+            visibleItems.push(overflowItems[itemId]);
+        }
+        for (const itemId of invisibleItemQueue){
+            itemVisibility[itemId] = false;
+            invisibleItems.push(overflowItems[itemId]);
+        }
+        // Set the snapshot first so `getSnapshot()` is current for both subscribers and any
+        // `onUpdateOverflow` consumer that reads it.
+        takeSnapshot({
+            itemVisibility,
+            groupVisibility,
+            invisibleItemCount: invisibleItems.length
+        });
+        // Legacy event payload: ordered item entries for `onUpdateOverflow` consumers.
         options.onUpdateOverflow({
             visibleItems,
             invisibleItems,
-            groupVisibility: groupManager.groupVisibility()
+            groupVisibility
         });
     };
+    const getSnapshot = ()=>snapshot;
     const processOverflowItems = ()=>{
         if (!container) {
             return false;
@@ -153,39 +191,78 @@ import { createPriorityQueue } from './priorityQueue';
         }
     };
     const update = debounce(forceUpdate);
-    const observe = (observedContainer, userOptions)=>{
+    const setOptions = (nextOptions)=>{
+        if (options === nextOptions) {
+            return;
+        }
+        const shouldTriggerUpdate = nextOptions.overflowAxis && options.overflowAxis !== nextOptions.overflowAxis || nextOptions.overflowDirection && options.overflowDirection !== nextOptions.overflowDirection || nextOptions.padding && options.padding !== nextOptions.padding || nextOptions.minimumVisible && options.minimumVisible !== nextOptions.minimumVisible || nextOptions.hasHiddenItems && options.hasHiddenItems !== nextOptions.hasHiddenItems;
+        Object.assign(options, nextOptions);
+        if (shouldTriggerUpdate) {
+            forceDispatch = true;
+            update();
+        }
+    };
+    const observe = (observedContainer, observeOptions)=>{
+        const { forceUpdate: shouldForceUpdate, ...userOptions } = observeOptions !== null && observeOptions !== void 0 ? observeOptions : {};
         Object.assign(options, userOptions);
-        observing = true;
-        Object.values(overflowItems).forEach((item)=>visibleItemQueue.enqueue(item.id));
+        Object.values(overflowItems).forEach((item)=>{
+            if (!visibleItemQueue.contains(item.id) && !invisibleItemQueue.contains(item.id)) {
+                visibleItemQueue.enqueue(item.id);
+            }
+        });
         container = observedContainer;
+        observing = true;
         disposeResizeObserver = observeResize(container, (entries)=>{
             if (!entries[0] || !container) {
                 return;
             }
             update();
         });
+        if (shouldForceUpdate && getClientSize(observedContainer) > 0) {
+            forceUpdate();
+        }
     };
-    const addItem = (item)=>{
-        if (overflowItems[item.id]) {
+    const disconnect = ()=>{
+        disposeResizeObserver();
+        disposeResizeObserver = ()=>{
+        /* noop */ };
+        // reset flags
+        container = undefined;
+        observing = false;
+        forceDispatch = true;
+        // clear all entries
+        Object.keys(overflowItems).forEach((itemId)=>removeItem(itemId));
+        Object.keys(overflowDividers).forEach((dividerId)=>removeDivider(dividerId));
+        removeOverflowMenu();
+        sizeCache.clear();
+        // notify subscribers that the manager is no longer tracking anything
+        takeSnapshot(EMPTY_SNAPSHOT);
+    };
+    const addItem = (items)=>{
+        if (overflowItems[items.id]) {
             return;
         }
-        overflowItems[item.id] = item;
+        overflowItems[items.id] = items;
         // some options can affect priority which are only set on `observe`
         if (observing) {
             // Updates to elements might not change the queue tops
             // i.e. new element is enqueued but the top of the queue stays the same
             // force a dispatch on the next batched update
             forceDispatch = true;
-            visibleItemQueue.enqueue(item.id);
+            visibleItemQueue.enqueue(items.id);
+            update();
         }
-        if (item.groupId) {
-            groupManager.addItem(item.id, item.groupId);
-            item.element.setAttribute(DATA_OVERFLOW_GROUP, item.groupId);
+        if (items.groupId) {
+            groupManager.addItem(items.id, items.groupId);
+            items.element.setAttribute(DATA_OVERFLOW_GROUP, items.groupId);
         }
-        update();
     };
     const addOverflowMenu = (el)=>{
         overflowMenu = el;
+        if (observing) {
+            forceDispatch = true;
+            update();
+        }
     };
     const addDivider = (divider)=>{
         if (!divider.groupId || overflowDividers[divider.groupId]) {
@@ -196,6 +273,10 @@ import { createPriorityQueue } from './priorityQueue';
     };
     const removeOverflowMenu = ()=>{
         overflowMenu = undefined;
+        if (observing) {
+            forceDispatch = true;
+            update();
+        }
     };
     const removeDivider = (groupId)=>{
         if (!overflowDividers[groupId]) {
@@ -225,19 +306,15 @@ import { createPriorityQueue } from './priorityQueue';
         }
         sizeCache.delete(item.element);
         delete overflowItems[itemId];
-        update();
+        if (observing) {
+            update();
+        }
     };
-    const disconnect = ()=>{
-        disposeResizeObserver();
-        // reset flags
-        container = undefined;
-        observing = false;
-        forceDispatch = true;
-        // clear all entries
-        Object.keys(overflowItems).forEach((itemId)=>removeItem(itemId));
-        Object.keys(overflowDividers).forEach((dividerId)=>removeDivider(dividerId));
-        removeOverflowMenu();
-        sizeCache.clear();
+    const subscribe = (listener)=>{
+        listeners.add(listener);
+        return ()=>{
+            listeners.delete(listener);
+        };
     };
     return {
         addItem,
@@ -249,7 +326,10 @@ import { createPriorityQueue } from './priorityQueue';
         addOverflowMenu,
         removeOverflowMenu,
         addDivider,
-        removeDivider
+        removeDivider,
+        setOptions,
+        getSnapshot,
+        subscribe
     };
 }
 const createGroupManager = ()=>{