refactor(react-overflow): move first-paint force into manager observe

Split the priority-overflow option types into `OverflowOptions` (config,
used by createOverflowManager/setOptions) and `ObserveOptions` (extends
`Partial<OverflowOptions>` with `forceUpdate?`). The first-paint force and
its measurement guard now live inside the manager's `observe` method, so
`useOverflowContainer` just calls `observe(container, { forceUpdate: true })`
instead of guarding and forcing at the call site. The guard reuses the
manager's axis-aware `getClientSize` helper so it agrees with the actual
overflow measurement on what "measured" means.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: bsunderhus

packages/react-components/priority-overflow/etc/priority-overflow.api.md

@@ -5,20 +5,14 @@
 ```ts
 
 // @internal
-export function createOverflowManager(initialOptions?: Partial<ObserveOptions>): OverflowManager;
+export function createOverflowManager(initialOptions?: Partial<OverflowOptions>): OverflowManager;
 
 // @internal
 export const EMPTY_SNAPSHOT: OverflowSnapshot;
 
-// @public
-export interface ObserveOptions {
-    hasHiddenItems?: boolean;
-    minimumVisible?: number;
-    onUpdateItemVisibility: OnUpdateItemVisibility;
-    onUpdateOverflow: OnUpdateOverflow;
-    overflowAxis?: OverflowAxis;
-    overflowDirection?: OverflowDirection;
-    padding?: number;
+// @public (undocumented)
+export interface ObserveOptions extends Partial<OverflowOptions> {
+    forceUpdate?: boolean;
 }
 
 // @public
@@ -76,11 +70,22 @@ export interface OverflowManager {
     removeDivider: (groupId: string) => void;
     removeItem: (itemId: string) => void;
     removeOverflowMenu: () => void;
-    setOptions: (options: Partial<ObserveOptions>) => void;
+    setOptions: (options: Partial<OverflowOptions>) => void;
     subscribe: (listener: () => void) => () => void;
     update: () => void;
 }
 
+// @public
+export interface OverflowOptions {
+    hasHiddenItems?: boolean;
+    minimumVisible?: number;
+    onUpdateItemVisibility: OnUpdateItemVisibility;
+    onUpdateOverflow: OnUpdateOverflow;
+    overflowAxis?: OverflowAxis;
+    overflowDirection?: OverflowDirection;
+    padding?: number;
+}
+
 // @public
 export interface OverflowSnapshot {
     groupVisibility: Record<string, OverflowGroupState>;

packages/react-components/priority-overflow/src/index.ts

@@ -2,6 +2,7 @@ export { createOverflowManager } from './overflowManager';
 export { EMPTY_SNAPSHOT } from './consts';
 export type {
   ObserveOptions,
+  OverflowOptions,
   OnUpdateItemVisibility,
   OnUpdateItemVisibilityPayload,
   OnUpdateOverflow,

packages/react-components/priority-overflow/src/overflowManager.test.ts

@@ -175,4 +175,52 @@ describe('overflowManager', () => {
       invisibleItemCount: 0,
     });
   });
+
+  it('resolves overflow synchronously when observed with forceUpdate and the container is measured', () => {
+    const manager = createOverflowManager(createObserveOptions());
+    const container = createContainer(100);
+    const itemA = createElementWithSize('button', 60);
+    const itemB = createElementWithSize('button', 60);
+    const menu = createElementWithSize('button', 30);
+
+    manager.addItem({ element: itemA, id: 'a', priority: 1 });
+    manager.addItem({ element: itemB, id: 'b', priority: 0 });
+    manager.addOverflowMenu(menu);
+
+    // No manual forceUpdate(); observing with forceUpdate resolves overflow on its own.
+    manager.observe(container, { forceUpdate: true });
+
+    expect(getVisibleIds(manager)).toEqual(['a']);
+    expect(getInvisibleIds(manager)).toEqual(['b']);
+  });
+
+  it('does not resolve overflow on observe when forceUpdate is not requested', () => {
+    const manager = createOverflowManager(createObserveOptions());
+    const container = createContainer(100);
+    const itemA = createElementWithSize('button', 60);
+    const itemB = createElementWithSize('button', 60);
+
+    manager.addItem({ element: itemA, id: 'a', priority: 1 });
+    manager.addItem({ element: itemB, id: 'b', priority: 0 });
+
+    manager.observe(container);
+
+    // Nothing has been computed yet (the ResizeObserver is mocked to a noop).
+    expect(manager.getSnapshot().itemVisibility).toEqual({});
+  });
+
+  it('does not resolve overflow on observe with forceUpdate when the container is not measured', () => {
+    const manager = createOverflowManager(createObserveOptions());
+    const container = createContainer(0);
+    const itemA = createElementWithSize('button', 60);
+    const itemB = createElementWithSize('button', 60);
+
+    manager.addItem({ element: itemA, id: 'a', priority: 1 });
+    manager.addItem({ element: itemB, id: 'b', priority: 0 });
+
+    // Degenerate 0 size — the guard skips the force so nothing collapses.
+    manager.observe(container, { forceUpdate: true });
+
+    expect(manager.getSnapshot().itemVisibility).toEqual({});
+  });
 });

packages/react-components/priority-overflow/src/overflowManager.ts

@@ -7,12 +7,12 @@ import type {
   OverflowGroupState,
   OverflowItemEntry,
   OverflowManager,
-  ObserveOptions,
+  OverflowOptions,
   OverflowDividerEntry,
   OverflowSnapshot,
 } from './types';
 
-const DEFAULT_OPTIONS: Required<ObserveOptions> = {
+const DEFAULT_OPTIONS: Required<OverflowOptions> = {
   overflowAxis: 'horizontal',
   overflowDirection: 'end',
   padding: 10,
@@ -33,7 +33,7 @@ const DEFAULT_OPTIONS: Required<ObserveOptions> = {
  * @param initialOptions - Initial observe options. Missing values are filled with defaults.
  * @returns overflow manager instance
  */
-export function createOverflowManager(initialOptions: Partial<ObserveOptions> = {}): OverflowManager {
+export function createOverflowManager(initialOptions: Partial<OverflowOptions> = {}): OverflowManager {
   // 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<HTMLElement, number>();
@@ -44,7 +44,7 @@ export function createOverflowManager(initialOptions: Partial<ObserveOptions> =
   // If true, next update will dispatch to onUpdateOverflow even if queue top states don't change
   // Initially true to force dispatch on first mount
   let forceDispatch = true;
-  const options: Required<ObserveOptions> = { ...DEFAULT_OPTIONS, ...initialOptions };
+  const options: Required<OverflowOptions> = { ...DEFAULT_OPTIONS, ...initialOptions };
   const overflowItems: Record<string, OverflowItemEntry> = {};
   const overflowDividers: Record<string, OverflowDividerEntry> = {};
   const listeners = new Set<() => void>();
@@ -264,10 +264,10 @@ export function createOverflowManager(initialOptions: Partial<ObserveOptions> =
     }
   };
 
-  const observe: OverflowManager['observe'] = (observedContainer, userOptions) => {
-    if (userOptions) {
-      Object.assign(options, userOptions);
-    }
+  const observe: OverflowManager['observe'] = (observedContainer, observeOptions) => {
+    const { forceUpdate: shouldForceUpdate, ...userOptions } = observeOptions ?? {};
+    Object.assign(options, userOptions);
+
     Object.values(overflowItems).forEach(item => {
       if (!visibleItemQueue.contains(item.id) && !invisibleItemQueue.contains(item.id)) {
         visibleItemQueue.enqueue(item.id);
@@ -282,6 +282,10 @@ export function createOverflowManager(initialOptions: Partial<ObserveOptions> =
       }
       update();
     });
+
+    if (shouldForceUpdate && getClientSize(observedContainer) > 0) {
+      forceUpdate();
+    }
   };
 
   const disconnect: OverflowManager['disconnect'] = () => {

packages/react-components/priority-overflow/src/types.ts

@@ -130,7 +130,7 @@ export interface OnUpdateItemVisibilityPayload {
 /**
  * Options used to initialize or reconfigure overflow observation.
  */
-export interface ObserveOptions {
+export 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)
@@ -172,6 +172,14 @@ export interface ObserveOptions {
   hasHiddenItems?: boolean;
 }
 
+export interface ObserveOptions extends Partial<OverflowOptions> {
+  /**
+   * 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
+   */
+  forceUpdate?: boolean;
+}
+
 /**
  * Internal manager contract used to observe and compute priority overflow.
  *
@@ -189,7 +197,7 @@ export interface OverflowManager {
   /**
    * Updates engine options without restarting observation.
    */
-  setOptions: (options: Partial<ObserveOptions>) => void;
+  setOptions: (options: Partial<OverflowOptions>) => void;
   /**
    * Add overflow items
    */

packages/react-components/react-overflow/library/etc/react-overflow.api.md

@@ -4,11 +4,11 @@
 
 ```ts
 
-import type { ObserveOptions } from '@fluentui/priority-overflow';
 import type { OnUpdateOverflow } from '@fluentui/priority-overflow';
 import type { OverflowDividerEntry } from '@fluentui/priority-overflow';
 import type { OverflowGroupState } from '@fluentui/priority-overflow';
 import type { OverflowItemEntry } from '@fluentui/priority-overflow';
+import type { OverflowOptions } from '@fluentui/priority-overflow';
 import type { OverflowSnapshot } from '@fluentui/priority-overflow';
 import * as React_2 from 'react';
 
@@ -29,7 +29,7 @@ export interface OnOverflowChangeData extends OverflowState {
 }
 
 // @public
-export const Overflow: React_2.ForwardRefExoticComponent<Partial<Pick<ObserveOptions, "padding" | "overflowDirection" | "overflowAxis" | "minimumVisible" | "hasHiddenItems">> & {
+export const Overflow: React_2.ForwardRefExoticComponent<Partial<Pick<OverflowOptions, "padding" | "overflowDirection" | "overflowAxis" | "minimumVisible" | "hasHiddenItems">> & {
     children: React_2.ReactElement;
     onOverflowChange?: (ev: null, data: OverflowState) => void;
 } & React_2.RefAttributes<unknown>>;
@@ -54,7 +54,7 @@ export type OverflowItemProps = {
 });
 
 // @public
-export type OverflowProps = Partial<Pick<ObserveOptions, 'overflowAxis' | 'overflowDirection' | 'padding' | 'minimumVisible' | 'hasHiddenItems'>> & {
+export type OverflowProps = Partial<Pick<OverflowOptions, 'overflowAxis' | 'overflowDirection' | 'padding' | 'minimumVisible' | 'hasHiddenItems'>> & {
     children: React_2.ReactElement;
     onOverflowChange?: (ev: null, data: OverflowState) => void;
 };
@@ -69,7 +69,7 @@ export function useIsOverflowGroupVisible(id: string): OverflowGroupState;
 export function useIsOverflowItemVisible(id: string): boolean;
 
 // @internal (undocumented)
-export const useOverflowContainer: <TElement extends HTMLElement>(update: OnUpdateOverflow, options: Omit<ObserveOptions, "onUpdateOverflow">) => UseOverflowContainerReturn<TElement>;
+export const useOverflowContainer: <TElement extends HTMLElement>(update: OnUpdateOverflow, options: Omit<OverflowOptions, "onUpdateOverflow">) => UseOverflowContainerReturn<TElement>;
 
 // @internal (undocumented)
 export interface UseOverflowContainerReturn<TElement extends HTMLElement> extends Pick<OverflowContextValue, 'registerItem' | 'updateOverflow' | 'forceUpdateOverflow' | 'registerOverflowMenu' | 'registerDivider' | 'getSnapshot' | 'subscribe'> {

packages/react-components/react-overflow/library/src/components/Overflow.firstPaint.test.tsx

@@ -2,12 +2,13 @@
 
 import * as React from 'react';
 import { mergeClasses } from '@griffel/react';
-import type { ObserveOptions, OnUpdateOverflow, OverflowGroupState } from '@fluentui/priority-overflow';
+import type { OverflowOptions, OnUpdateOverflow, OverflowGroupState } from '@fluentui/priority-overflow';
 import {
   applyTriggerPropsToChildren,
   getTriggerChild,
   getReactElementRef,
   useMergedRefs,
+  useEventCallback,
 } from '@fluentui/react-utilities';
 
 import { OverflowContext, type OverflowContextValue } from '../overflowContext';
@@ -26,7 +27,7 @@ export interface OnOverflowChangeData extends OverflowState {}
  * Overflow Props
  */
 export type OverflowProps = Partial<
-  Pick<ObserveOptions, 'overflowAxis' | 'overflowDirection' | 'padding' | 'minimumVisible' | 'hasHiddenItems'>
+  Pick<OverflowOptions, 'overflowAxis' | 'overflowDirection' | 'padding' | 'minimumVisible' | 'hasHiddenItems'>
 > & {
   children: React.ReactElement;
 
@@ -51,21 +52,15 @@ export const Overflow = React.forwardRef((props: OverflowProps, ref) => {
     hasHiddenItems,
   } = props;
 
-  const update: OnUpdateOverflow = React.useCallback(
-    () => {
-      const snapshot = getSnapshot();
-      const state: OverflowState = {
-        hasOverflow: snapshot.invisibleItemCount > 0,
-        itemVisibility: snapshot.itemVisibility,
-        groupVisibility: snapshot.groupVisibility,
-      };
-      onOverflowChange?.(null, state);
-    },
-    // `getSnapshot` is a stable callback from useOverflowContainer (declared just below); omitted
-    // from deps to avoid a temporal-dead-zone reference.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [onOverflowChange],
-  );
+  const update: OnUpdateOverflow = useEventCallback(() => {
+    const snapshot = getSnapshot();
+    const state: OverflowState = {
+      hasOverflow: snapshot.invisibleItemCount > 0,
+      itemVisibility: snapshot.itemVisibility,
+      groupVisibility: snapshot.groupVisibility,
+    };
+    onOverflowChange?.(null, state);
+  });
 
   const {
     containerRef,