refactor(react-overflow,priority-overflow): make manager creation pure and lifecycle strict-mode safe

Restructure the priority-overflow manager and the react-overflow container hook so
that manager creation is render-pure and the observation lifecycle is colocated.

priority-overflow:
- createOverflowManager now accepts initialOptions and merges them over defaults
- new setOptions method updates engine options without re-creating the manager
- observe(container) returns a cleanup function that stops observation only
  (item, divider, and overflow menu registrations are no longer torn down)
- disconnect is preserved as a shortcut for the latest observe cleanup
- introduce OverflowManagerOptions type alias and complete tsdoc on the surface

react-overflow:
- create the manager via useMemo so React renders stay pure
- start observation in a single useIsomorphicLayoutEffect and return the
  observe cleanup as the effect cleanup
- propagate option changes through setOptions instead of rebuilding the manager
- ref-guard the overflow menu and divider deregistration so strict-mode double
  invocation does not unregister a freshly mounted element

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bsunderhus

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

@@ -4,10 +4,10 @@
 
 ```ts
 
-// @internal (undocumented)
-export function createOverflowManager(): OverflowManager;
+// @internal
+export function createOverflowManager(initialOptions?: Partial<ObserveOptions>): OverflowManager;
 
-// @public (undocumented)
+// @public
 export interface ObserveOptions {
     hasHiddenItems?: boolean;
     minimumVisible?: number;
@@ -18,67 +18,61 @@ export interface ObserveOptions {
     padding?: number;
 }
 
-// @public (undocumented)
+// @public
 export type OnUpdateItemVisibility = (data: OnUpdateItemVisibilityPayload) => void;
 
-// @public (undocumented)
+// @public
 export interface OnUpdateItemVisibilityPayload {
-    // (undocumented)
     item: OverflowItemEntry;
-    // (undocumented)
     visible: boolean;
 }
 
 // @public
 export type OnUpdateOverflow = (data: OverflowEventPayload) => void;
 
-// @public (undocumented)
+// @public
 export type OverflowAxis = 'horizontal' | 'vertical';
 
-// @public (undocumented)
+// @public
 export type OverflowDirection = 'start' | 'end';
 
-// @public (undocumented)
+// @public
 export interface OverflowDividerEntry {
     element: HTMLElement;
-    // (undocumented)
     groupId: string;
 }
 
 // @public
 export interface OverflowEventPayload {
-    // (undocumented)
     groupVisibility: Record<string, OverflowGroupState>;
-    // (undocumented)
     invisibleItems: OverflowItemEntry[];
-    // (undocumented)
     visibleItems: OverflowItemEntry[];
 }
 
-// @public (undocumented)
+// @public
 export type OverflowGroupState = 'visible' | 'hidden' | 'overflow';
 
-// @public (undocumented)
+// @public
 export interface OverflowItemEntry {
     element: HTMLElement;
-    // (undocumented)
     groupId?: string;
     id: string;
     pinned?: boolean;
     priority: number;
 }
 
-// @internal (undocumented)
+// @internal
 export interface OverflowManager {
     addDivider: (divider: OverflowDividerEntry) => void;
-    addItem: (items: OverflowItemEntry) => void;
+    addItem: (item: OverflowItemEntry) => void;
     addOverflowMenu: (element: HTMLElement) => void;
     disconnect: () => void;
     forceUpdate: () => void;
-    observe: (container: HTMLElement, options: ObserveOptions) => void;
+    observe: (container: HTMLElement) => () => void;
     removeDivider: (groupId: string) => void;
     removeItem: (itemId: string) => void;
     removeOverflowMenu: () => void;
+    setOptions: (options: Partial<ObserveOptions>) => void;
     update: () => void;
 }
 

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

@@ -0,0 +1,133 @@
+import { createOverflowManager } from './overflowManager';
+import type { ObserveOptions, OverflowEventPayload } from './types';
+
+describe('overflowManager', () => {
+  beforeAll(() => {
+    global.ResizeObserver = class ResizeObserver {
+      public observe() {
+        // do nothing
+      }
+
+      public unobserve() {
+        // do nothing
+      }
+
+      public disconnect() {
+        // do nothing
+      }
+    } as unknown as typeof ResizeObserver;
+  });
+
+  const createElementWithSize = (tagName: string, width: number) => {
+    const element = document.createElement(tagName);
+    Object.defineProperty(element, 'offsetWidth', { configurable: true, value: width });
+    Object.defineProperty(element, 'offsetHeight', { configurable: true, value: width });
+
+    return element;
+  };
+
+  const createContainer = (width: number) => {
+    const container = document.createElement('div');
+    Object.defineProperty(container, 'clientWidth', { configurable: true, value: width });
+    Object.defineProperty(container, 'clientHeight', { configurable: true, value: width });
+
+    return container;
+  };
+
+  const createObserveOptions = (options: Partial<ObserveOptions> = {}): ObserveOptions => ({
+    overflowAxis: 'horizontal',
+    overflowDirection: 'end',
+    padding: 10,
+    minimumVisible: 0,
+    hasHiddenItems: false,
+    onUpdateItemVisibility: jest.fn(),
+    onUpdateOverflow: jest.fn(),
+    ...options,
+  });
+
+  const lastDispatch = (onUpdateOverflow: jest.Mock): OverflowEventPayload =>
+    onUpdateOverflow.mock.calls[onUpdateOverflow.mock.calls.length - 1][0];
+
+  it('should dispatch overflow update after forceUpdate', () => {
+    const onUpdateOverflow = jest.fn();
+    const manager = createOverflowManager(createObserveOptions({ onUpdateOverflow }));
+    const container = createContainer(100);
+    const itemA = createElementWithSize('button', 40);
+    const itemB = createElementWithSize('button', 40);
+    const menu = createElementWithSize('button', 20);
+
+    manager.addItem({ element: itemA, id: 'a', priority: 1 });
+    manager.addItem({ element: itemB, id: 'b', priority: 0 });
+    manager.addOverflowMenu(menu);
+    manager.observe(container);
+    manager.forceUpdate();
+
+    const dispatch = lastDispatch(onUpdateOverflow);
+    expect(dispatch.visibleItems.map(item => item.id).sort()).toEqual(['a', 'b']);
+    expect(dispatch.invisibleItems).toEqual([]);
+    expect(dispatch.groupVisibility).toEqual({});
+  });
+
+  it('should re-dispatch when setOptions changes a relevant option', () => {
+    const onUpdateOverflow = jest.fn();
+    const manager = createOverflowManager(createObserveOptions({ onUpdateOverflow }));
+    const container = createContainer(100);
+    const itemA = createElementWithSize('button', 40);
+    const itemB = createElementWithSize('button', 40);
+    const menu = createElementWithSize('button', 20);
+
+    manager.addItem({ element: itemA, id: 'a', priority: 1 });
+    manager.addItem({ element: itemB, id: 'b', priority: 0 });
+    manager.addOverflowMenu(menu);
+    manager.observe(container);
+    manager.forceUpdate();
+
+    onUpdateOverflow.mockClear();
+    manager.setOptions({ padding: 30 });
+
+    expect(onUpdateOverflow).toHaveBeenCalled();
+    const dispatch = lastDispatch(onUpdateOverflow);
+    expect(dispatch.visibleItems.map(item => item.id)).toEqual(['a']);
+    expect(dispatch.invisibleItems.map(item => item.id)).toEqual(['b']);
+  });
+
+  it('observe should return a cleanup that allows re-observation', () => {
+    const onUpdateOverflow = jest.fn();
+    const manager = createOverflowManager(createObserveOptions({ onUpdateOverflow }));
+    const container = createContainer(100);
+    const item = createElementWithSize('button', 40);
+
+    manager.addItem({ element: item, id: 'a', priority: 1 });
+    const cleanup = manager.observe(container);
+    manager.forceUpdate();
+    expect(lastDispatch(onUpdateOverflow).visibleItems.map(i => i.id)).toEqual(['a']);
+
+    cleanup();
+    onUpdateOverflow.mockClear();
+
+    manager.observe(container);
+    manager.forceUpdate();
+    expect(onUpdateOverflow).toHaveBeenCalled();
+    expect(lastDispatch(onUpdateOverflow).visibleItems.map(i => i.id)).toEqual(['a']);
+  });
+
+  it('should remove items through removeItem', () => {
+    const onUpdateOverflow = jest.fn();
+    const manager = createOverflowManager(createObserveOptions({ onUpdateOverflow }));
+    const container = createContainer(100);
+    const item = createElementWithSize('button', 40);
+
+    manager.addItem({ element: item, id: 'a', priority: 1 });
+    manager.observe(container);
+    manager.forceUpdate();
+
+    expect(lastDispatch(onUpdateOverflow).visibleItems.map(i => i.id)).toEqual(['a']);
+
+    manager.removeItem('a');
+    manager.forceUpdate();
+
+    const dispatch = lastDispatch(onUpdateOverflow);
+    expect(dispatch.visibleItems).toEqual([]);
+    expect(dispatch.invisibleItems).toEqual([]);
+  });
+});

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

@@ -11,11 +11,24 @@ import type {
   OverflowDividerEntry,
 } from './types';
 
+const DEFAULT_OPTIONS: Required<ObserveOptions> = {
+  overflowAxis: 'horizontal',
+  overflowDirection: 'end',
+  padding: 10,
+  minimumVisible: 0,
+  hasHiddenItems: false,
+  onUpdateItemVisibility: () => undefined,
+  onUpdateOverflow: () => undefined,
+};
+
 /**
+ * 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(): OverflowManager {
+export function createOverflowManager(initialOptions: Partial<ObserveOptions> = {}): 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>();
@@ -26,16 +39,7 @@ export function createOverflowManager(): OverflowManager {
   // 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> = {
-    padding: 10,
-    overflowAxis: 'horizontal',
-    overflowDirection: 'end',
-    minimumVisible: 0,
-    onUpdateItemVisibility: () => undefined,
-    onUpdateOverflow: () => undefined,
-    hasHiddenItems: false,
-  };
-
+  const options: Required<ObserveOptions> = { ...DEFAULT_OPTIONS, ...initialOptions };
   const overflowItems: Record<string, OverflowItemEntry> = {};
   const overflowDividers: Record<string, OverflowDividerEntry> = {};
   let disposeResizeObserver: () => void = () => null;
@@ -205,21 +209,65 @@ export function createOverflowManager(): OverflowManager {
 
   const update: OverflowManager['update'] = debounce(forceUpdate);
 
-  const observe: OverflowManager['observe'] = (observedContainer, userOptions) => {
-    Object.assign(options, userOptions);
-    observing = true;
-    Object.values(overflowItems).forEach(item => visibleItemQueue.enqueue(item.id));
+  const setOptions: OverflowManager['setOptions'] = nextOptions => {
+    if (options === nextOptions) {
+      return;
+    }
+    const previousAxis = options.overflowAxis;
+    const previousDirection = options.overflowDirection;
+    const previousPadding = options.padding;
+    const previousMinimumVisible = options.minimumVisible;
+    const previousHasHiddenItems = options.hasHiddenItems;
+
+    Object.assign(options, nextOptions);
+
+    if (
+      previousAxis !== options.overflowAxis ||
+      previousDirection !== options.overflowDirection ||
+      previousPadding !== options.padding ||
+      previousMinimumVisible !== options.minimumVisible ||
+      previousHasHiddenItems !== options.hasHiddenItems
+    ) {
+      forceDispatch = true;
+      update();
+    }
+  };
+
+  let observeCleanup: () => void = () => null;
+
+  const observe: OverflowManager['observe'] = observedContainer => {
+    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();
     });
+
+    const cleanup = () => {
+      if (container !== observedContainer) {
+        return;
+      }
+      disposeResizeObserver();
+      disposeResizeObserver = () => null;
+      container = undefined;
+      observing = false;
+      forceDispatch = true;
+    };
+
+    observeCleanup = cleanup;
+    return cleanup;
   };
 
+  const disconnect: OverflowManager['disconnect'] = () => observeCleanup();
+
   const addItem: OverflowManager['addItem'] = item => {
     if (overflowItems[item.id]) {
       return;
@@ -234,14 +282,13 @@ export function createOverflowManager(): OverflowManager {
       // force a dispatch on the next batched update
       forceDispatch = true;
       visibleItemQueue.enqueue(item.id);
+      update();
     }
 
     if (item.groupId) {
       groupManager.addItem(item.id, item.groupId);
       item.element.setAttribute(DATA_OVERFLOW_GROUP, item.groupId);
     }
-
-    update();
   };
 
   const addOverflowMenu: OverflowManager['addOverflowMenu'] = el => {
@@ -294,22 +341,9 @@ export function createOverflowManager(): OverflowManager {
 
     sizeCache.delete(item.element);
     delete overflowItems[itemId];
-    update();
-  };
-
-  const disconnect: OverflowManager['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();
+    if (observing) {
+      update();
+    }
   };
 
   return {
@@ -323,6 +357,7 @@ export function createOverflowManager(): OverflowManager {
     removeOverflowMenu,
     addDivider,
     removeDivider,
+    setOptions,
   };
 }