@khanacademy/wonder-blocks-popover 3.2.8 → 3.2.10

package/src/components/popover.tsx

@@ -16,8 +16,9 @@ import PopoverContentCore from "./popover-content-core";
 import PopoverContext from "./popover-context";
 import PopoverAnchor from "./popover-anchor";
 import PopoverDialog from "./popover-dialog";
-import FocusManager from "./focus-manager";
 import PopoverEventListener from "./popover-event-listener";
+import InitialFocus from "./initial-focus";
+import FocusManager from "./focus-manager";
 
 type PopoverContents =
     | React.ReactElement<React.ComponentProps<typeof PopoverContent>>
@@ -101,6 +102,20 @@ type Props = AriaProps &
          * Whether to show the popover tail or not. Defaults to true.
          */
         showTail: boolean;
+        /**
+         * Optional property to enable the portal functionality of popover.
+         * This is very handy in cases where the Popover can't be easily
+         * injected into the DOM structure and requires portaling to
+         * the trigger location.
+         *
+         * Set to "true" by default.
+         *
+         * CAUTION: Turning off portal could cause some clipping issues
+         * especially around legacy code with usage of z-indexing,
+         * Use caution when turning this functionality off and ensure
+         * your content does not get clipped or hidden.
+         */
+        portal?: boolean;
     }>;
 
 type State = Readonly<{
@@ -121,6 +136,7 @@ type State = Readonly<{
 type DefaultProps = Readonly<{
     placement: Props["placement"];
     showTail: Props["showTail"];
+    portal: Props["portal"];
 }>;
 
 /**
@@ -150,6 +166,7 @@ export default class Popover extends React.Component<Props, State> {
     static defaultProps: DefaultProps = {
         placement: "top",
         showTail: true,
+        portal: true,
     };
 
     /**
@@ -255,33 +272,54 @@ export default class Popover extends React.Component<Props, State> {
     }
 
     renderPopper(uniqueId: string): React.ReactNode {
-        const {initialFocusId, placement, showTail} = this.props;
+        const {
+            initialFocusId,
+            placement,
+            showTail,
+            portal,
+            "aria-label": ariaLabel,
+        } = this.props;
         const {anchorElement} = this.state;
 
-        return (
-            <FocusManager
-                anchorElement={anchorElement}
-                initialFocusId={initialFocusId}
-            >
-                <TooltipPopper
+        const ariaDescribedBy = ariaLabel ? undefined : `${uniqueId}-content`;
+        const ariaLabelledBy = ariaLabel ? undefined : `${uniqueId}-title`;
+
+        const popperContent = (
+            <TooltipPopper anchorElement={anchorElement} placement={placement}>
+                {(props: PopperElementProps) => (
+                    <PopoverDialog
+                        {...props}
+                        aria-label={ariaLabel}
+                        aria-describedby={ariaDescribedBy}
+                        aria-labelledby={ariaLabelledBy}
+                        id={uniqueId}
+                        onUpdate={(placement) => this.setState({placement})}
+                        showTail={showTail}
+                    >
+                        {this.renderContent(uniqueId)}
+                    </PopoverDialog>
+                )}
+            </TooltipPopper>
+        );
+
+        if (portal) {
+            return (
+                <FocusManager
                     anchorElement={anchorElement}
-                    placement={placement}
+                    initialFocusId={initialFocusId}
                 >
-                    {(props: PopperElementProps) => (
-                        <PopoverDialog
-                            {...props}
-                            aria-describedby={`${uniqueId}-content`}
-                            aria-labelledby={`${uniqueId}-title`}
-                            id={uniqueId}
-                            onUpdate={(placement) => this.setState({placement})}
-                            showTail={showTail}
-                        >
-                            {this.renderContent(uniqueId)}
-                        </PopoverDialog>
-                    )}
-                </TooltipPopper>
-            </FocusManager>
-        );
+                    {popperContent}
+                </FocusManager>
+            );
+        } else {
+            return (
+                // Ensures the user is focused on the first available element
+                // when popover is rendered without the focus manager.
+                <InitialFocus initialFocusId={initialFocusId}>
+                    {popperContent}
+                </InitialFocus>
+            );
+        }
     }
 
     getHost(): Element | null | undefined {
@@ -295,10 +333,29 @@ export default class Popover extends React.Component<Props, State> {
         );
     }
 
+    renderPortal(uniqueId: string, opened: boolean) {
+        if (!opened) {
+            return null;
+        }
+
+        const {portal} = this.props;
+        const popperHost = this.getHost();
+
+        // Attach the popover to a Portal
+        if (portal && popperHost) {
+            return ReactDOM.createPortal(
+                this.renderPopper(uniqueId),
+                popperHost,
+            );
+        }
+
+        // Otherwise, append the dialog next to the trigger element
+        return this.renderPopper(uniqueId);
+    }
+
     render(): React.ReactNode {
         const {children, dismissEnabled, id} = this.props;
         const {opened, placement} = this.state;
-        const popperHost = this.getHost();
 
         return (
             <PopoverContext.Provider
@@ -319,12 +376,7 @@ export default class Popover extends React.Component<Props, State> {
                             >
                                 {children}
                             </PopoverAnchor>
-                            {popperHost &&
-                                opened &&
-                                ReactDOM.createPortal(
-                                    this.renderPopper(uniqueId),
-                                    popperHost,
-                                )}
+                            {this.renderPortal(uniqueId, opened)}
                         </React.Fragment>
                     )}
                 </IDProvider>