breaking(Menu): Replacing hoistToBody with renderToPortal functionality

Author: jamesmfriedman

.storybook/config.js

@@ -2,6 +2,7 @@ import React from 'react';
 import { configure, addDecorator } from '@storybook/react';
 import { withKnobs } from '@storybook/addon-knobs';
 import '../src/rmwc/styles';
+import { Portal } from '@rmwc/base';
 
 function requireAll(requireContext) {
   return requireContext.keys().map(requireContext);
@@ -23,7 +24,15 @@ const StylesDecorator = storyFn => (
   </div>
 );
 
+const PortalDecorator = storyFn => (
+  <>
+    {storyFn()}
+    <Portal />
+  </>
+);
+
 addDecorator(withKnobs);
 addDecorator(StylesDecorator);
+addDecorator(PortalDecorator);
 
 configure(loadStories, module);

src/base/index.tsx

@@ -5,5 +5,6 @@ export * from './with-theme';
 export * from './utils';
 export * from './foundation-component';
 export * from './component';
+export * from './portal';
 
 export type WithThemeProps = _WithThemeProps;

src/base/portal.tsx

@@ -0,0 +1,44 @@
+import React, { useRef, useEffect, useState } from 'react';
+import ReactDOM from 'react-dom';
+
+const PORTAL_ID = 'rmwcPortal';
+
+export type PortalPropT = Element | string | boolean | undefined | null;
+
+export function Portal() {
+  const el = useRef(document.createElement('div'));
+
+  return <div ref={el} id={PORTAL_ID} />;
+}
+
+export function PortalChild({
+  children,
+  renderTo
+}: {
+  children: React.ReactNode;
+  renderTo?: PortalPropT;
+}) {
+  const [portalEl, setPortalEl] = useState<Element | undefined>();
+
+  useEffect(() => {
+    let element: Element | undefined = undefined;
+
+    if (renderTo === true) {
+      element = document.getElementById(PORTAL_ID) || undefined;
+    } else if (typeof renderTo === 'string') {
+      element = document.querySelector(renderTo) || undefined;
+    } else if (renderTo instanceof Element) {
+      element = renderTo;
+    }
+
+    if (element !== portalEl) {
+      setPortalEl(element);
+    }
+  }, [renderTo, portalEl]);
+
+  if (portalEl) {
+    return ReactDOM.createPortal(children, portalEl);
+  }
+
+  return <>{children}</>;
+}

src/base/utils/index.tsx

@@ -13,3 +13,4 @@ export * from './get-display-name';
 export * from './empty-client-rect';
 export * from './data-table-context';
 export * from './trigger-window-resize';
+export * from './raf';

src/base/utils/raf.tsx

@@ -0,0 +1,14 @@
+/**
+ * A helper for when we have multiple requestion animation frames
+ * Usage:
+ *  raf(() => doSomething, 3);
+ */
+export const raf = (
+  callback: () => void,
+  frames: number = 1,
+  _iteration = 1
+) => {
+  window.requestAnimationFrame(() => {
+    _iteration >= frames ? callback() : raf(callback, frames, _iteration + 1);
+  });
+};

src/menu/generated-examples.json

@@ -1 +1 @@
-["function Example() {\n  const [open, setOpen] = React.useState(false);\n\n  return (\n    <MenuSurfaceAnchor>\n      <Menu\n        open={open}\n        onSelect={evt => console.log(evt.detail.index)}\n        onClose={evt => setOpen(false)}\n      >\n        <MenuItem>Cookies</MenuItem>\n        <MenuItem>Pizza</MenuItem>\n        {/** MenuItem is just a ListItem, so you can intermingle other List components */}\n        <ListDivider />\n        <MenuItem>Icecream</MenuItem>\n      </Menu>\n\n      <Button raised onClick={evt => setOpen(!open)}>\n        Menu\n      </Button>\n    </MenuSurfaceAnchor>\n  );\n}","function Example() {\n  const [open, setOpen] = React.useState(false);\n\n  return (\n    <MenuSurfaceAnchor>\n      <MenuSurface open={open} onClose={evt => setOpen(false)}>\n        <div style={{ padding: '1rem', width: '8rem' }}>\n          Make the content whatever you want.\n        </div>\n      </MenuSurface>\n\n      <Button raised onClick={evt => setOpen(!open)}>\n        Menu Surface\n      </Button>\n    </MenuSurfaceAnchor>\n  );\n}","function Example() {\n  const [open, setOpen] = React.useState(false);\n\n  return (\n    <MenuSurfaceAnchor>\n      <MenuSurface open={open} onClose={evt => setOpen(false)}>\n        <div style={{ padding: '1rem', width: '8rem' }}>Menu</div>\n      </MenuSurface>\n      {/** The handle can be any component you want */}\n      <IconButton icon=\"menu\" onClick={evt => setOpen(!open)} />\n    </MenuSurfaceAnchor>\n  );\n}","<SimpleMenu handle={<Button>Simple Menu</Button>}>\n  <MenuItem>Cookies</MenuItem>\n  <MenuItem>Pizza</MenuItem>\n  <MenuItem>Icecream</MenuItem>\n</SimpleMenu>","<SimpleMenuSurface handle={<Button>Simple Menu Surface</Button>}>\n  <div style={{ padding: '1rem', width: '8rem' }}>\n    Make the content whatever you want.\n  </div>\n</SimpleMenuSurface>","function Example() {\n  const [anchorCorner, setAnchorCorner] = React.useState(\n    'topLeft'\n  );\n\n  return (\n    <>\n      <MenuSurfaceAnchor>\n        <MenuSurface anchorCorner={anchorCorner} open={true}>\n          <div style={{ padding: '1rem', width: '8rem' }}>\n            anchorCorner: {anchorCorner}\n          </div>\n        </MenuSurface>\n        <Button raised label=\"Anchored Menu\" />\n      </MenuSurfaceAnchor>\n\n      <Select\n        value={anchorCorner}\n        label=\"anchorCorner\"\n        onChange={evt => setAnchorCorner(evt.currentTarget.value)}\n        options={[\n          'topLeft',\n          'topRight',\n          'bottomLeft',\n          'bottomRight',\n          'topStart',\n          'topEnd',\n          'bottomStart',\n          'bottomEnd'\n        ]}\n      />\n    </>\n  );\n}"]
+["function Example() {\n  const [open, setOpen] = React.useState(false);\n\n  return (\n    <MenuSurfaceAnchor>\n      <Menu\n        open={open}\n        onSelect={evt => console.log(evt.detail.index)}\n        onClose={evt => setOpen(false)}\n      >\n        <MenuItem>Cookies</MenuItem>\n        <MenuItem>Pizza</MenuItem>\n        {/** MenuItem is just a ListItem, so you can intermingle other List components */}\n        <ListDivider />\n        <MenuItem>Icecream</MenuItem>\n      </Menu>\n\n      <Button raised onClick={evt => setOpen(!open)}>\n        Menu\n      </Button>\n    </MenuSurfaceAnchor>\n  );\n}","function Example() {\n  const [open, setOpen] = React.useState(false);\n\n  return (\n    <MenuSurfaceAnchor>\n      <MenuSurface open={open} onClose={evt => setOpen(false)}>\n        <div style={{ padding: '1rem', width: '8rem' }}>\n          Make the content whatever you want.\n        </div>\n      </MenuSurface>\n\n      <Button raised onClick={evt => setOpen(!open)}>\n        Menu Surface\n      </Button>\n    </MenuSurfaceAnchor>\n  );\n}","function Example() {\n  const [open, setOpen] = React.useState(false);\n\n  return (\n    <MenuSurfaceAnchor>\n      <MenuSurface open={open} onClose={evt => setOpen(false)}>\n        <div style={{ padding: '1rem', width: '8rem' }}>Menu</div>\n      </MenuSurface>\n      {/** The handle can be any component you want */}\n      <IconButton icon=\"menu\" onClick={evt => setOpen(!open)} />\n    </MenuSurfaceAnchor>\n  );\n}","<SimpleMenu handle={<Button>Simple Menu</Button>}>\n  <MenuItem>Cookies</MenuItem>\n  <MenuItem>Pizza</MenuItem>\n  <MenuItem>Icecream</MenuItem>\n</SimpleMenu>","<SimpleMenuSurface handle={<Button>Simple Menu Surface</Button>}>\n  <div style={{ padding: '1rem', width: '8rem' }}>\n    Make the content whatever you want.\n  </div>\n</SimpleMenuSurface>","function Example() {\n  const [anchorCorner, setAnchorCorner] = React.useState(\n    'topLeft'\n  );\n\n  return (\n    <>\n      <MenuSurfaceAnchor>\n        <MenuSurface anchorCorner={anchorCorner} open={true}>\n          <div style={{ padding: '1rem', width: '8rem' }}>\n            anchorCorner: {anchorCorner}\n          </div>\n        </MenuSurface>\n        <Button raised label=\"Anchored Menu\" />\n      </MenuSurfaceAnchor>\n\n      <Select\n        value={anchorCorner}\n        label=\"anchorCorner\"\n        onChange={evt => setAnchorCorner(evt.currentTarget.value)}\n        options={[\n          'topLeft',\n          'topRight',\n          'bottomLeft',\n          'bottomRight',\n          'topStart',\n          'topEnd',\n          'bottomStart',\n          'bottomEnd'\n        ]}\n      />\n    </>\n  );\n}","\n  // Somewhere at the top level of your app\n  // Render the RMWC Portal\n  // You only have to do this once\n  import React from 'react';\n  import { Portal } from '@rmwc/base';\n\n  export default function App() {\n    return (\n      <div>\n        ...\n        <Portal />\n      </div>\n    )\n  }\n","function Example() {\n  const [renderToPortal, setRenderToPortal] = React.useState(true);\n  const options = ['Cookies', 'Pizza', 'Icecream'];\n  return (\n    <>\n      <div\n        style={{\n          marginBottom: '10rem',\n          height: '3.5rem',\n          overflow: 'hidden'\n        }}\n      >\n        <MenuSurfaceAnchor>\n          <Button raised>Open Menu</Button>\n          <Menu open renderToPortal={renderToPortal}>\n            {options.map(o => (\n              <MenuItem key={o}>{o}</MenuItem>\n            ))}\n          </Menu>\n        </MenuSurfaceAnchor>\n      </div>\n      <Checkbox\n        checked={renderToPortal}\n        onChange={evt => setRenderToPortal(evt.currentTarget.checked)}\n        label=\"renderToPortal\"\n      />\n    </>\n  );\n}"]

src/menu/menu-surface-foundation.tsx

@@ -2,7 +2,8 @@ import {
   useFoundation,
   closest,
   emptyClientRect,
-  FoundationElement
+  FoundationElement,
+  raf
 } from '@rmwc/base';
 import { MenuSurfaceProps, MenuSurfaceApi } from './menu-surface';
 
@@ -39,7 +40,6 @@ export const useMenuSurfaceFoundation = (
   const firstFocusableElementRef = useRef<HTMLElement | null>(null);
   const previousFocusRef = useRef<HTMLElement | null>(null);
   const anchorElementRef = useRef<HTMLElement | null>(null);
-  const hoistedRef = useRef(false);
 
   const { foundation, ...elements } = useFoundation({
     props,
@@ -52,7 +52,9 @@ export const useMenuSurfaceFoundation = (
       rootEl: FoundationElement<any, any>;
     }): MenuSurfaceApi => {
       return {
-        hoistMenuToBody: () => hoistMenuToBody(),
+        hoistMenuToBody: () => {
+          // this is controlled by the renderToPortal prop
+        },
         setAnchorCorner: (corner: Corner) => foundation.setAnchorCorner(corner),
         setAnchorElement: (element: HTMLElement) =>
           (anchorElementRef.current = element),
@@ -233,32 +235,6 @@ export const useMenuSurfaceFoundation = (
 
   rootEl.setProp('onKeyDown', handleKeydown, true);
 
-  const hoistMenuToBody = useCallback(() => {
-    if (rootEl.ref?.parentElement) {
-      document.body.appendChild(
-        rootEl.ref.parentElement.removeChild(rootEl.ref)
-      );
-      hoistedRef.current = true;
-      foundation.setIsHoisted(true);
-
-      // correct layout for open menu
-      if (foundation.isOpen()) {
-        // wait an extra frame so that the element is actually
-        // done being hoisted and painting. Fixes Issue #453
-        // @ts-ignore unsafe private variable access
-        window.requestAnimationFrame(() => foundation.autoPosition_());
-      }
-    }
-  }, [foundation, rootEl.ref]);
-
-  const unhoistMenuFromBody = useCallback(() => {
-    if (anchorElementRef.current && rootEl.ref) {
-      anchorElementRef.current.appendChild(rootEl.ref);
-      hoistedRef.current = false;
-      foundation.setIsHoisted(false);
-    }
-  }, [foundation, rootEl.ref]);
-
   // fixed
   useEffect(() => {
     foundation.setFixedPosition(!!props.fixed);
@@ -277,12 +253,34 @@ export const useMenuSurfaceFoundation = (
     }
   }, [rootEl.ref]);
 
-  // hoistToBody
+  // renderToPortal
   useEffect(() => {
-    if (props.hoistToBody !== undefined) {
-      props.hoistToBody ? hoistMenuToBody() : unhoistMenuFromBody();
-    }
-  }, [props.hoistToBody, foundation, hoistMenuToBody, unhoistMenuFromBody]);
+    props.renderToPortal
+      ? foundation.setIsHoisted(true)
+      : foundation.setIsHoisted(false);
+
+    const autoPosition = () => {
+      try {
+        // silence this, it blows up loudly occasionally
+        // @ts-ignore unsafe private variable access
+        foundation.autoPosition_();
+      } catch (err) {}
+    };
+
+    // wait an extra frame so that the element is actually
+    // done being hoisted and painting. Fixes Issue #453
+    const handler = props.renderToPortal ? autoPosition : () => {};
+
+    raf(() => {
+      foundation.isOpen() && autoPosition();
+    });
+
+    // fix positioning on window resize when renderToPortal is true
+    window.addEventListener('resize', handler);
+    return () => {
+      window.removeEventListener('resize', handler);
+    };
+  }, [props.renderToPortal, foundation]);
 
   // anchorCorner
   useEffect(() => {
@@ -315,28 +313,17 @@ export const useMenuSurfaceFoundation = (
       // changing the open prop externally, while also not
       // conflicting with any internal events that might have closed
       // the menu, like a body click or escape key
-      window.requestAnimationFrame(() => {
-        window.requestAnimationFrame(() => {
-          if (foundation.isOpen()) {
-            foundation.close();
-          }
-        });
-      });
+      raf(() => {
+        if (foundation.isOpen()) {
+          foundation.close();
+        }
+      }, 2);
     }
   }, [open, foundation, rootEl.ref]);
 
   useEffect(() => {
     setOpen(!!props.open);
   }, [props.open]);
 
-  useEffect(() => {
-    return () => {
-      // @ts-ignore Fixes unsafe access from MDC when component unmounts
-      foundation.adapter_.notifyClose = () => {};
-      unhoistMenuFromBody();
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
-
   return { ...elements };
 };

src/menu/menu-surface.tsx

@@ -3,6 +3,7 @@ import React from 'react';
 import { Corner, MDCMenuSurfaceFoundation } from '@material/menu-surface';
 import { useClassNames, Tag, createComponent } from '@rmwc/base';
 import { useMenuSurfaceFoundation } from './menu-surface-foundation';
+import { PortalChild, PortalPropT } from '@rmwc/base';
 
 export type AnchorT =
   | 'bottomEnd'
@@ -30,8 +31,8 @@ export interface MenuSurfaceProps {
   open?: boolean;
   /** Make the menu position fixed. */
   fixed?: boolean;
-  /** Moves the menu to the body. Useful for situations where the content might be cutoff by an overflow: hidden container. */
-  hoistToBody?: boolean;
+  /** Renders the menu to a portal. Useful for situations where the content might be cutoff by an overflow: hidden container. You can pass "true" to render to the default RMWC portal. */
+  renderToPortal?: PortalPropT;
   /** Manually position the menu to one of the corners. */
   anchorCorner?: AnchorT;
   /** Callback for when the menu is opened. */
@@ -59,7 +60,7 @@ export const MenuSurface = createComponent<MenuSurfaceProps>(
       anchorCorner,
       onOpen,
       onClose,
-      hoistToBody,
+      renderToPortal,
       fixed,
       apiRef,
       foundationRef,
@@ -76,9 +77,11 @@ export const MenuSurface = createComponent<MenuSurfaceProps>(
     ]);
 
     return (
-      <Tag {...rest} element={rootEl} className={className} ref={ref}>
-        {children}
-      </Tag>
+      <PortalChild renderTo={renderToPortal}>
+        <Tag {...rest} element={rootEl} className={className} ref={ref}>
+          {children}
+        </Tag>
+      </PortalChild>
     );
   }
 );

src/menu/menu.story.tsx

@@ -122,7 +122,11 @@ function MenuHoist() {
         >
           Open Menu
         </Button>
-        <Menu open={open} hoistToBody={hoisted} onClose={() => setOpen(false)}>
+        <Menu
+          open={open}
+          renderToPortal={hoisted}
+          onClose={() => setOpen(false)}
+        >
           {options.map((o: string) => (
             <MenuItem key={o}>{o}</MenuItem>
           ))}
@@ -145,7 +149,12 @@ storiesOf('Menus', module)
       </Menu>
     );
   })
-  .add('Menu: hoistToBody', () => <MenuHoist />)
+  .add('Menu: hoistToBody', () => (
+    <>
+      <MenuHoist />
+      <MenuHoist />
+    </>
+  ))
   .add('SimpleMenu', () => (
     <SimpleMenu handle={<Button raised>Open Simple Menu</Button>}>
       <MenuItem>Cookies</MenuItem>

src/menu/readme.tsx

@@ -17,6 +17,7 @@ import { ListDivider } from '../list';
 import { Button } from '../button';
 import { Select } from '../select';
 import { IconButton } from '../icon-button';
+import { Checkbox } from '../checkbox';
 
 export default function() {
   return (
@@ -128,7 +129,7 @@ export default function() {
       <DocsSubtitle>Anchoring</DocsSubtitle>
       <DocsP>
         By default, Menus will attempt to automatically position themselves, but
-        this behavior can be overriden by setting the `anchorCorner` prop.
+        this behavior can be overridden by setting the `anchorCorner` prop.
       </DocsP>
 
       <DocsExample>
@@ -168,6 +169,75 @@ export default function() {
         }}
       </DocsExample>
 
+      <DocsSubtitle>Rendering through Portals</DocsSubtitle>
+      <DocsP>
+        Occasionally, you may find your menu being cut off from being inside a
+        container that is styled to be `overflow:hidden`. RMWC provides a
+        `renderToPortal` prop that lets you use React's portal functionality to
+        render the menu dropdown in a different container.
+      </DocsP>
+
+      <DocsP>
+        You can specify any element or selector you want, but the simplest
+        method is to pass `true` and use RMWC's built in `Portal` component.
+      </DocsP>
+
+      <DocsExample codeOnly>
+        {/* jsx */ `
+          // Somewhere at the top level of your app
+          // Render the RMWC Portal
+          // You only have to do this once
+          import React from 'react';
+          import { Portal } from '@rmwc/base';
+
+          export default function App() {
+            return (
+              <div>
+                ...
+                <Portal />
+              </div>
+            )
+          }
+        `}
+      </DocsExample>
+
+      <DocsP>
+        Now you can use the `renderToPortal` prop. Below is a contrived example
+        of a menu being cut off due to `overflow: hidden`.
+      </DocsP>
+
+      <DocsExample>
+        {function Example() {
+          const [renderToPortal, setRenderToPortal] = React.useState(true);
+          const options = ['Cookies', 'Pizza', 'Icecream'];
+          return (
+            <>
+              <div
+                style={{
+                  marginBottom: '10rem',
+                  height: '3.5rem',
+                  overflow: 'hidden'
+                }}
+              >
+                <MenuSurfaceAnchor>
+                  <Button raised>Open Menu</Button>
+                  <Menu open renderToPortal={renderToPortal}>
+                    {options.map(o => (
+                      <MenuItem key={o}>{o}</MenuItem>
+                    ))}
+                  </Menu>
+                </MenuSurfaceAnchor>
+              </div>
+              <Checkbox
+                checked={renderToPortal}
+                onChange={evt => setRenderToPortal(evt.currentTarget.checked)}
+                label="renderToPortal"
+              />
+            </>
+          );
+        }}
+      </DocsExample>
+
       <DocProps
         src={propsSrc}
         components={[