feat(react-overflow): allow opting out of first-paint correctness

First-paint correctness is now *requested* by the default item/menu hooks:
useOverflowItem and useOverflowMenu call forceUpdateOverflow on registration,
which the container honors by resolving overflow synchronously in its observe
layout effect (deferring the request until it observes, via child-before-parent
effect ordering). A hot-path consumer that builds a custom item hook on top of
useOverflowContext and omits the forceUpdateOverflow call opts the container out
of the synchronous first-paint pass entirely — the ResizeObserver then drives
the first (async) overflow pass instead. No new Overflow prop or public export;
the opt-out is intentionally low-profile.

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

Author: bsunderhus

change/@fluentui-react-overflow-pr4-opt-out.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: allow opting out of first-paint overflow correctness for hot-path consumers",
+  "packageName": "@fluentui/react-overflow",
+  "email": "bsunderhus@microsoft.com",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-overflow/library/src/Overflow.paint-probe.cy.tsx

@@ -4,10 +4,12 @@ import {
   Overflow,
   OverflowItem,
   useOverflowMenu,
+  useOverflowContext,
+  useOverflowCount,
   type OverflowProps,
   type OverflowItemProps,
 } from '@fluentui/react-overflow';
-import type { DistributiveOmit } from '@fluentui/react-utilities';
+import { useIsomorphicLayoutEffect, type DistributiveOmit } from '@fluentui/react-utilities';
 
 // Disable StrictMode so the probe measures a single mount/commit path.
 const mount = (element: React.ReactElement) => mountBase(element, { strict: false });
@@ -113,6 +115,54 @@ const Menu = () => {
   );
 };
 
+// Opt-out hooks: equivalent to useOverflowItem / useOverflowMenu but WITHOUT requesting first-paint
+// correctness (no forceUpdateOverflow on registration). This is how a hot-path consumer opts the
+// container out of the synchronous first-paint pass — no Overflow prop, just a custom item/menu hook.
+const useOptOutOverflowItem = <TElement extends HTMLElement>(id: string): React.RefObject<TElement | null> => {
+  const ref = React.useRef<TElement | null>(null);
+  const registerItem = useOverflowContext(v => v.registerItem);
+  useIsomorphicLayoutEffect(() => {
+    if (ref.current) {
+      return registerItem({ element: ref.current, id, priority: 0 });
+    }
+  }, [id, registerItem]);
+  return ref;
+};
+
+const useOptOutOverflowMenu = <TElement extends HTMLElement>() => {
+  const ref = React.useRef<TElement | null>(null);
+  const overflowCount = useOverflowCount();
+  const registerOverflowMenu = useOverflowContext(v => v.registerOverflowMenu);
+  const isOverflowing = overflowCount > 0;
+  useIsomorphicLayoutEffect(() => {
+    if (ref.current) {
+      return registerOverflowMenu(ref.current);
+    }
+  }, [registerOverflowMenu, isOverflowing]);
+  return { ref, overflowCount, isOverflowing };
+};
+
+const OptOutItem = ({ children, width, id }: { children?: React.ReactNode; width?: number; id: string }) => {
+  const ref = useOptOutOverflowItem<HTMLButtonElement>(id);
+  return (
+    <button ref={ref} {...{ [selectors.item]: id }} style={{ width: width ?? 50, height: 50, flexShrink: 0 }}>
+      {children}
+    </button>
+  );
+};
+
+const OptOutMenu = () => {
+  const { isOverflowing, ref, overflowCount } = useOptOutOverflowMenu<HTMLButtonElement>();
+  if (!isOverflowing) {
+    return null;
+  }
+  return (
+    <button {...{ [selectors.menu]: '' }} ref={ref} style={{ width: 50, height: 50, flexShrink: 0 }}>
+      +{overflowCount}
+    </button>
+  );
+};
+
 const PaintPhaseProbe: React.FC<{ name: string }> = ({ name }) => {
   // The probe deliberately distinguishes the layout phase from the passive effect phase,
   // so it must use the non-isomorphic variant.
@@ -284,4 +334,38 @@ describe('Overflow paint probe', () => {
       overflowingItemIds: [],
     });
   });
+
+  it('defers overflow past first paint when items and menu opt out of first-paint correctness', { retries: 0 }, () => {
+    const mapHelper = new Array(10).fill(0).map((_, i) => i);
+
+    mount(
+      <PaintPhaseProbeHarness name="opt-out">
+        <Container size={300}>
+          {mapHelper.map(i => (
+            <OptOutItem key={i} id={i.toString()}>
+              {i}
+            </OptOutItem>
+          ))}
+          <OptOutMenu />
+        </Container>
+      </PaintPhaseProbeHarness>,
+    );
+
+    // The opt-out hooks never call forceUpdateOverflow, so nothing requests the synchronous
+    // first-paint pass. At the synchronous commit (layout phase) overflow is therefore unresolved —
+    // the eager cases above collapse items here instead. The ResizeObserver resolves it afterwards.
+    cy.get(`[${selectors.probe}="opt-out"] [${selectors.probePhase}="raf2"]`).should($node => {
+      expect($node.text(), 'probe snapshots written').not.to.equal('');
+    });
+    cy.get(`[${selectors.probe}="opt-out"]`).then($probe => {
+      const layout = JSON.parse($probe.find(`[${selectors.probePhase}="layout"]`).text()) as PaintPhaseSnapshot;
+      expect(layout, 'first paint (layout) is unresolved when opting out of first-paint correctness').to.deep.equal({
+        menuText: null,
+        overflowingItemIds: [],
+      });
+    });
+
+    // It still resolves eventually — the ResizeObserver drives the deferred overflow pass.
+    cy.get(`[${selectors.menu}]`).should('exist');
+  });
 });

packages/react-components/react-overflow/library/src/useOverflowContainer.ts

@@ -56,15 +56,27 @@ export const useOverflowContainer = <TElement extends HTMLElement>(
 
   const managerRef = React.useRef<OverflowManager | null>(null);
 
+  // Whether the container's observe effect has run. Item/menu hooks request first-paint correctness
+  // via `forceUpdateOverflow`; before the container observes there is nothing to compute yet, so the
+  // request is recorded here and honored when the observe effect runs.
+  const hasObservedRef = React.useRef(false);
+  // Set when a descendant requests first-paint correctness before the container observes. The default
+  // item/menu hooks make this request; a hook that omits it opts the container out of the synchronous
+  // first-paint pass (the hot path), letting the ResizeObserver drive the first overflow pass instead.
+  const pendingForceUpdateRef = React.useRef(false);
+
   if (managerRef.current === null) {
     managerRef.current = canUseDOM() ? createOverflowManager(observeOptions) : null;
   }
 
   useIsomorphicLayoutEffect(() => {
     if (managerRef.current && containerRef.current) {
-      // forceUpdate resolves overflow synchronously for a correct first paint; the manager guards it
-      // on the container being measured.
-      managerRef.current.observe(containerRef.current, { forceUpdate: true });
+      // Child item/menu effects already ran (child-before-parent), so `pendingForceUpdateRef`
+      // reflects whether any descendant requested first-paint correctness. When requested, resolve
+      // overflow synchronously so the first paint is correct; the manager guards the force on the
+      // container being measured.
+      managerRef.current.observe(containerRef.current, { forceUpdate: pendingForceUpdateRef.current });
+      hasObservedRef.current = true;
       return () => managerRef.current?.disconnect();
     }
   }, []);
@@ -120,7 +132,14 @@ export const useOverflowContainer = <TElement extends HTMLElement>(
   );
 
   const forceUpdateOverflow = React.useCallback(() => {
-    managerRef.current?.forceUpdate();
+    // Before the container observes, a force can't compute anything (it isn't observing yet), so
+    // record the request and let the observe effect honor it (first-paint correctness). After
+    // observing, force directly.
+    if (hasObservedRef.current) {
+      managerRef.current?.forceUpdate();
+    } else {
+      pendingForceUpdateRef.current = true;
+    }
   }, []);
 
   return {

packages/react-components/react-overflow/library/src/useOverflowItem.test.tsx

@@ -11,6 +11,7 @@ const mockContextValue = (options: Partial<OverflowContextValue> = {}) =>
     itemVisibility: {},
     registerItem: jest.fn(),
     updateOverflow: jest.fn(),
+    forceUpdateOverflow: jest.fn(),
     ...options,
   } as OverflowContextValue);
 

packages/react-components/react-overflow/library/src/useOverflowItem.ts

@@ -22,6 +22,7 @@ export function useOverflowItem<TElement extends HTMLElement>(
 ): React.RefObject<TElement | null> {
   const ref = React.useRef<TElement | null>(null);
   const registerItem = useOverflowContext(v => v.registerItem);
+  const forceUpdateOverflow = useOverflowContext(v => v.forceUpdateOverflow);
 
   useIsomorphicLayoutEffect(() => {
     if (process.env.NODE_ENV !== 'production') {
@@ -35,15 +36,20 @@ export function useOverflowItem<TElement extends HTMLElement>(
     }
 
     if (ref.current) {
-      return registerItem({
+      const unregister = registerItem({
         element: ref.current,
         id,
         priority: priority ?? 0,
         groupId,
         pinned,
       });
+      // Request first-paint correctness. Before the container observes this defers a synchronous
+      // force to the container's observe effect; after, it recomputes for the (re)registered item.
+      // An item hook that omits this call opts the container out of the synchronous first-paint pass.
+      forceUpdateOverflow();
+      return unregister;
     }
-  }, [id, priority, registerItem, groupId, pinned]);
+  }, [id, priority, registerItem, forceUpdateOverflow, groupId, pinned]);
 
   return ref;
 }