docs: Add documentation for react-overflow

change/@fluentui-react-overflow-6feccff5-e359-4581-af14-16837f78dab2.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "docs: Add documentation for package",
+  "packageName": "@fluentui/react-overflow",
+  "email": "[email protected]",
+  "dependentChangeType": "none"
+}

packages/react-components/react-overflow/stories/Overflow/Default.stories.tsx

@@ -0,0 +1,83 @@
+import * as React from 'react';
+import {
+  makeStyles,
+  shorthands,
+  Button,
+  Menu,
+  MenuTrigger,
+  MenuPopover,
+  MenuList,
+  MenuItem,
+  MenuButton,
+} from '@fluentui/react-components';
+import {
+  Overflow,
+  OverflowItem,
+  OverflowItemProps,
+  useIsOverflowItemVisible,
+  useOverflowMenu,
+} from '@fluentui/react-components/unstable';
+
+const useStyles = makeStyles({
+  container: {
+    display: 'flex',
+    flexWrap: 'nowrap',
+    minWidth: 0,
+    ...shorthands.overflow('hidden'),
+  },
+});
+
+export const Default = () => {
+  const styles = useStyles();
+
+  const itemIds = new Array(8).fill(0).map((_, i) => i.toString());
+
+  return (
+    <Overflow>
+      <div className={styles.container}>
+        {itemIds.map(i => (
+          <OverflowItem key={i} id={i}>
+            <Button>Item {i}</Button>
+          </OverflowItem>
+        ))}
+        <OverflowMenu itemIds={itemIds} />
+      </div>
+    </Overflow>
+  );
+};
+
+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>
+  );
+};

packages/react-components/react-overflow/stories/Overflow/Dividers.stories.tsx

@@ -1,7 +1,24 @@
 import * as React from 'react';
-import { makeStyles, shorthands } from '@fluentui/react-components';
-import { Overflow } from '@fluentui/react-overflow';
-import { OverflowMenu, TestOverflowGroupDivider, TestOverflowItem } from './utils.stories';
+import {
+  makeStyles,
+  shorthands,
+  Button,
+  Divider,
+  Menu,
+  MenuTrigger,
+  MenuPopover,
+  MenuList,
+  MenuItem,
+  MenuDivider,
+  MenuButton,
+} from '@fluentui/react-components';
+import {
+  Overflow,
+  OverflowItem,
+  useIsOverflowGroupVisible,
+  useIsOverflowItemVisible,
+  useOverflowMenu,
+} from '@fluentui/react-components/unstable';
 
 const useStyles = makeStyles({
   container: {
@@ -18,22 +35,115 @@ export const Dividers = () => {
   return (
     <Overflow overflowDirection="start" padding={30}>
       <div className={styles.container}>
-        <TestOverflowItem id={'1'} groupId={'1'} />
-        <TestOverflowGroupDivider groupId={'1'} />
-        <TestOverflowItem id={'2'} groupId={'2'} />
-        <TestOverflowGroupDivider groupId={'2'} />
-        <TestOverflowItem id={'3'} groupId={'3'} />
-        <TestOverflowItem id={'4'} groupId={'3'} />
-        <TestOverflowGroupDivider groupId={'3'} />
-        <TestOverflowItem id={'5'} groupId={'4'} />
-        <TestOverflowItem id={'6'} groupId={'4'} />
-        <TestOverflowItem id={'7'} groupId={'4'} />
-        <TestOverflowGroupDivider groupId={'4'} />
-        <TestOverflowItem id={'8'} groupId={'5'} />
+        <OverflowItem id={'1'} groupId={'1'}>
+          <Button>Item 1</Button>
+        </OverflowItem>
+        <OverflowGroupDivider groupId={'1'} />
+        <OverflowItem id={'2'} groupId={'2'}>
+          <Button>Item 2</Button>
+        </OverflowItem>
+        <OverflowGroupDivider groupId={'2'} />
+        <OverflowItem id={'3'} groupId={'3'}>
+          <Button>Item 3</Button>
+        </OverflowItem>
+        <OverflowItem id={'4'} groupId={'3'}>
+          <Button>Item 4</Button>
+        </OverflowItem>
+        <OverflowGroupDivider groupId={'3'} />
+        <OverflowItem id={'5'} groupId={'4'}>
+          <Button>Item 5</Button>
+        </OverflowItem>
+        <OverflowItem id={'6'} groupId={'4'}>
+          <Button>Item 6</Button>
+        </OverflowItem>
+        <OverflowItem id={'7'} groupId={'4'}>
+          <Button>Item 7</Button>
+        </OverflowItem>
+        <OverflowGroupDivider groupId={'4'} />
+        <OverflowItem id={'8'} groupId={'5'}>
+          <Button>Item 8</Button>
+        </OverflowItem>
         <OverflowMenu
           itemIds={['1', 'divider-1', '2', 'divider-2', '3', '4', 'divider-3', '5', '6', '7', 'divider-4', '8']}
         />
       </div>
     </Overflow>
   );
 };
+
+const OverflowGroupDivider: React.FC<{
+  groupId: string;
+}> = props => {
+  const isGroupVisible = useIsOverflowGroupVisible(props.groupId);
+
+  if (isGroupVisible === 'hidden') {
+    return null;
+  }
+
+  return <Divider vertical appearance="brand" style={{ flexGrow: 0, paddingRight: '4px', paddingLeft: '4px' }} />;
+};
+
+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 => {
+            // This is purely a simplified convention for documentation examples
+            // Could be done in other ways too
+            if (typeof i === 'string' && i.startsWith('divider')) {
+              const groupId = i.split('-')[1];
+              return <OverflowMenuDivider key={i} id={groupId} />;
+            }
+            return <OverflowMenuItem key={i} id={i} />;
+          })}
+        </MenuList>
+      </MenuPopover>
+    </Menu>
+  );
+};
+
+const OverflowMenuItem: React.FC<{ id: string }> = props => {
+  const { id } = props;
+  const isVisible = useIsOverflowItemVisible(id);
+
+  if (isVisible) {
+    return null;
+  }
+
+  return <MenuItem>Item {id}</MenuItem>;
+};
+
+const OverflowMenuDivider: React.FC<{
+  id: string;
+}> = props => {
+  const isGroupVisible = useIsOverflowGroupVisible(props.id);
+
+  if (isGroupVisible === 'visible') {
+    return null;
+  }
+
+  return <MenuDivider />;
+};
+
+Dividers.parameters = {
+  docs: {
+    description: {
+      story: [
+        'Dividers can be handled by assigning groups to overflow items. The visibility of the divider',
+        'can be configured to depend on the overflow item group. This way dividers will also disappear',
+        'once its group is completely overflowed and avoids trailing or double dividers.',
+      ].join('\n'),
+    },
+  },
+};