feat: add onOverflowChange callback

change/@fluentui-react-overflow-a31beb0d-76b2-491e-add6-1f3fd27db85f.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: add `onOverflowChange` callback",
+  "packageName": "@fluentui/react-overflow",
+  "email": "lingfangao@hotmail.com",
+  "dependentChangeType": "patch"
+}

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

@@ -9,6 +9,7 @@ import {
   useIsOverflowGroupVisible,
   useOverflowMenu,
   useOverflowContext,
+  type OnOverflowChangeData,
 } from '@fluentui/react-overflow';
 import { Portal } from '@fluentui/react-portal';
 import { OverflowAxis } from '@fluentui/priority-overflow';
@@ -1066,4 +1067,47 @@ describe('Overflow', () => {
       cy.get('#toggle').click();
     }
   });
+
+  it('shoud call onOverflowChange', () => {
+    const itemCount = 10;
+    const mapHelper = new Array(itemCount).fill(0).map((_, i) => i);
+    let latestUpdate: OnOverflowChangeData | undefined;
+    mount(
+      <Container onOverflowChange={(e, data) => (latestUpdate = data)}>
+        {mapHelper.map(i => (
+          <Item key={i} id={i.toString()}>
+            {i}
+          </Item>
+        ))}
+        <Menu />
+      </Container>,
+    );
+    const overflowCases = [
+      { containerSize: 450, overflowCount: 2 },
+      { containerSize: 400, overflowCount: 3 },
+      { containerSize: 350, overflowCount: 4 },
+      { containerSize: 300, overflowCount: 5 },
+      { containerSize: 250, overflowCount: 6 },
+      { containerSize: 200, overflowCount: 7 },
+      { containerSize: 150, overflowCount: 8 },
+      { containerSize: 100, overflowCount: 9 },
+      { containerSize: 50, overflowCount: 10 },
+    ];
+
+    overflowCases.forEach(({ overflowCount, containerSize }) => {
+      setContainerWidth(containerSize);
+      cy.get(`[${selectors.menu}]`).should('have.text', `+${overflowCount}`);
+      cy.then(() => {
+        expect(latestUpdate?.hasOverflow).to.equal(true);
+        const visibleBoundary = itemCount - overflowCount;
+        for (let i = 0; i < visibleBoundary; i++) {
+          expect(latestUpdate?.itemVisibility[i.toString()]).to.equal(true);
+        }
+
+        for (let i = visibleBoundary; i < itemCount; i++) {
+          expect(latestUpdate?.itemVisibility[i.toString()]).to.equal(false);
+        }
+      });
+    });
+  });
 });

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

@@ -13,13 +13,19 @@ interface OverflowState {
   groupVisibility: Record<string, OverflowGroupState>;
 }
 
+export interface OnOverflowChangeData extends OverflowState {};
+
 /**
  * Overflow Props
  */
 export type OverflowProps = Partial<
   Pick<ObserveOptions, 'overflowAxis' | 'overflowDirection' | 'padding' | 'minimumVisible'>
 > & {
   children: React.ReactElement;
+
+  // overflow is not caused by DOM event
+  // eslint-disable-next-line @nx/workspace-consistent-callback-type
+  onOverflowChange?: (ev: null, data: OverflowState) => void;
 };
 
 /**
@@ -28,7 +34,7 @@ export type OverflowProps = Partial<
 export const Overflow = React.forwardRef((props: OverflowProps, ref) => {
   const styles = useOverflowStyles();
 
-  const { children, minimumVisible, overflowAxis = 'horizontal', overflowDirection, padding } = props;
+  const { children, minimumVisible, overflowAxis = 'horizontal', overflowDirection, padding, onOverflowChange } = props;
 
   const [overflowState, setOverflowState] = React.useState<OverflowState>({
     hasOverflow: false,
@@ -47,11 +53,15 @@ export const Overflow = React.forwardRef((props: OverflowProps, ref) => {
     invisibleItems.forEach(x => (itemVisibility[x.id] = false));
 
     setOverflowState(() => {
-      return {
+      const newState = {
         hasOverflow: data.invisibleItems.length > 0,
         itemVisibility,
         groupVisibility,
       };
+
+      onOverflowChange?.(null, { ...newState });
+
+      return newState;
     });
   };
 

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

@@ -1,5 +1,5 @@
 export { Overflow } from './components/Overflow';
-export type { OverflowProps } from './components/Overflow';
+export type { OverflowProps, OnOverflowChangeData } from './components/Overflow';
 export { DATA_OVERFLOWING, DATA_OVERFLOW_ITEM, DATA_OVERFLOW_MENU, DATA_OVERFLOW_DIVIDER } from './constants';
 export type { UseOverflowContainerReturn } from './types';
 export { useIsOverflowGroupVisible } from './useIsOverflowGroupVisible';

packages/react-components/react-overflow/stories/src/Overflow/ListenToChanges.stories.tsx

@@ -0,0 +1,121 @@
+import * as React from 'react';
+import {
+  makeStyles,
+  Button,
+  Menu,
+  MenuTrigger,
+  MenuPopover,
+  MenuList,
+  MenuItem,
+  MenuButton,
+  tokens,
+  mergeClasses,
+  Overflow,
+  OverflowItem,
+  OverflowItemProps,
+  useIsOverflowItemVisible,
+  useOverflowMenu,
+} from '@fluentui/react-components';
+
+const useStyles = makeStyles({
+  container: {
+    display: 'flex',
+    flexWrap: 'nowrap',
+    minWidth: 0,
+    overflow: 'hidden',
+  },
+
+  resizableArea: {
+    minWidth: '200px',
+    maxWidth: '800px',
+    border: `2px solid ${tokens.colorBrandBackground}`,
+    padding: '20px 10px 10px 10px',
+    position: 'relative',
+    resize: 'horizontal',
+    '::after': {
+      content: `'Resizable Area'`,
+      position: 'absolute',
+      padding: '1px 4px 1px',
+      top: '-2px',
+      left: '-2px',
+      fontFamily: 'monospace',
+      fontSize: '15px',
+      fontWeight: 900,
+      lineHeight: 1,
+      letterSpacing: '1px',
+      color: tokens.colorNeutralForegroundOnBrand,
+      backgroundColor: tokens.colorBrandBackground,
+    },
+  },
+});
+
+export const ListenToChanges = () => {
+  const styles = useStyles();
+
+  const itemIds = new Array(8).fill(0).map((_, i) => i.toString());
+  const [overflowState, setOverflowState] = React.useState<any>({});
+
+  return (
+    <>
+      <Overflow onOverflowChange={(e, data) => setOverflowState(data)}>
+        <div className={mergeClasses(styles.container, styles.resizableArea)}>
+          {itemIds.map(i => (
+            <OverflowItem key={i} id={i}>
+              <Button>Item {i}</Button>
+            </OverflowItem>
+          ))}
+          <OverflowMenu itemIds={itemIds} />
+        </div>
+      </Overflow>
+      <pre>{JSON.stringify(overflowState, null, 2)}</pre>
+    </>
+  );
+};
+
+const OverflowMenuItem: React.FC<Pick<OverflowItemProps, 'id'>> = props => {
+  const { id } = props;
+  const isVisible = useIsOverflowItemVisible(id);
+
+  if (isVisible) {
+    return null;
+  }
+
+  // As an union between button props and div props may be conflicting, casting is required
+  return <MenuItem>Item {id}</MenuItem>;
+};
+
+const OverflowMenu: React.FC<{ itemIds: string[] }> = ({ itemIds }) => {
+  const { ref, overflowCount, isOverflowing } = useOverflowMenu<HTMLButtonElement>();
+
+  if (!isOverflowing) {
+    return null;
+  }
+
+  return (
+    <Menu>
+      <MenuTrigger disableButtonEnhancement>
+        <MenuButton ref={ref}>+{overflowCount} items</MenuButton>
+      </MenuTrigger>
+
+      <MenuPopover>
+        <MenuList>
+          {itemIds.map(i => {
+            return <OverflowMenuItem key={i} id={i} />;
+          })}
+        </MenuList>
+      </MenuPopover>
+    </Menu>
+  );
+};
+
+ListenToChanges.parameters = {
+  docs: {
+    description: {
+      story: [
+        'You can listen to changes with the `onOnverflowChange` prop which will return the overflow',
+        'state. This can be useful when you have other UI features that need to be triggered on changes',
+        'to item visibility.',
+      ].join('\n'),
+    },
+  },
+};

packages/react-components/react-overflow/stories/src/Overflow/index.stories.tsx

@@ -12,6 +12,7 @@ export { Dividers } from './Dividers.stories';
 export { LargerDividers } from './LargerDividers.stories';
 export { PriorityWithDividers } from './PriorityWithDividers.stories';
 export { CustomComponent } from './CustomComponent.stories';
+export { ListenToChanges } from './ListenToChanges.stories';
 
 // Typing with as Meta<typeof Overflow> generates a type error for the `subcomponents` property.
 // https://github.com/storybookjs/storybook/issues/27535