React overflow/feature/refactor internals

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,70 +18,67 @@ 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;
+    getSnapshot: () => OverflowEventPayload;
+    observe: (container: HTMLElement) => () => void;
     removeDivider: (groupId: string) => void;
     removeItem: (itemId: string) => void;
     removeOverflowMenu: () => void;
+    setOptions: (options: Partial<OverflowManagerOptions>) => void;
+    subscribe: (listener: () => void) => () => void;
     update: () => void;
 }
 
-// (No @packageDocumentation comment for this package)
+// @public
+export type OverflowManagerOptions = ObserveOptions;
 
 ```

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

@@ -1,6 +1,12 @@
+/**
+ * Utilities for measuring container overflow and managing priority-based item visibility.
+ *
+ * @packageDocumentation
+ */
 export { createOverflowManager } from './overflowManager';
 export type {
   ObserveOptions,
+  OverflowManagerOptions,
   OnUpdateItemVisibility,
   OnUpdateItemVisibilityPayload,
   OnUpdateOverflow,

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

@@ -0,0 +1,147 @@
+import { createOverflowManager } from './overflowManager';
+import type { ObserveOptions } 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 getVisibleIds = (manager: ReturnType<typeof createOverflowManager>) =>
+    manager
+      .getSnapshot()
+      .visibleItems.map(item => item.id)
+      .sort();
+
+  const getInvisibleIds = (manager: ReturnType<typeof createOverflowManager>) =>
+    manager
+      .getSnapshot()
+      .invisibleItems.map(item => item.id)
+      .sort();
+
+  it('should expose a stable snapshot after forceUpdate', () => {
+    const manager = createOverflowManager();
+    const container = createContainer(100);
+    const itemA = createElementWithSize('button', 40);
+    const itemB = createElementWithSize('button', 40);
+    const menu = createElementWithSize('button', 20);
+
+    manager.setOptions(createObserveOptions());
+    manager.addItem({ element: itemA, id: 'a', priority: 1 });
+    manager.addItem({ element: itemB, id: 'b', priority: 0 });
+    manager.addOverflowMenu(menu);
+    manager.observe(container);
+    manager.forceUpdate();
+
+    expect(getVisibleIds(manager)).toEqual(['a', 'b']);
+    expect(getInvisibleIds(manager)).toEqual([]);
+    expect(manager.getSnapshot().groupVisibility).toEqual({});
+  });
+
+  it('should update snapshot and notify subscribers when options change', () => {
+    const manager = createOverflowManager();
+    const container = createContainer(100);
+    const itemA = createElementWithSize('button', 40);
+    const itemB = createElementWithSize('button', 40);
+    const menu = createElementWithSize('button', 20);
+    const listener = jest.fn();
+
+    manager.setOptions(createObserveOptions());
+    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 unsubscribe = manager.subscribe(listener);
+
+    manager.setOptions({ padding: 30 });
+
+    expect(listener).toHaveBeenCalled();
+    expect(getVisibleIds(manager)).toEqual(['a']);
+    expect(getInvisibleIds(manager)).toEqual(['b']);
+    expect(manager.getSnapshot().groupVisibility).toEqual({});
+
+    unsubscribe();
+  });
+
+  it('should reset snapshot state when observation cleanup runs', () => {
+    const manager = createOverflowManager();
+    const container = createContainer(100);
+    const item = createElementWithSize('button', 40);
+
+    manager.setOptions(createObserveOptions());
+    manager.addItem({ element: item, id: 'a', priority: 1 });
+    const cleanup = manager.observe(container);
+    manager.forceUpdate();
+
+    expect(getVisibleIds(manager)).toEqual(['a']);
+
+    cleanup();
+
+    expect(manager.getSnapshot()).toEqual({
+      visibleItems: [],
+      invisibleItems: [],
+      groupVisibility: {},
+    });
+  });
+
+  it('should remove items through removeItem', () => {
+    const manager = createOverflowManager();
+    const container = createContainer(100);
+    const item = createElementWithSize('button', 40);
+
+    manager.setOptions(createObserveOptions());
+    manager.addItem({ element: item, id: 'a', priority: 1 });
+    manager.observe(container);
+    manager.forceUpdate();
+
+    expect(getVisibleIds(manager)).toEqual(['a']);
+
+    manager.removeItem('a');
+    manager.forceUpdate();
+
+    expect(manager.getSnapshot()).toEqual({
+      visibleItems: [],
+      invisibleItems: [],
+      groupVisibility: {},
+    });
+  });
+});