@khanacademy/wonder-blocks-popover 3.2.8 → 3.2.10

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @khanacademy/wonder-blocks-popover
 
+## 3.2.10
+
+### Patch Changes
+
+-   68dd6059: adds optional aria label for popover
+-   Updated dependencies [be540444]
+    -   @khanacademy/wonder-blocks-tooltip@2.3.8
+
+## 3.2.9
+
+### Patch Changes
+
+-   47d680f4: Removed usage of focus management in Popover component, in favor of a similar implementation that won't override custom keyboard navigation.
+
 ## 3.2.8
 
 ### Patch Changes

package/dist/components/popover.d.ts

@@ -81,6 +81,20 @@ type Props = AriaProps & Readonly<{
      * 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<{
     /**
@@ -99,6 +113,7 @@ type State = Readonly<{
 type DefaultProps = Readonly<{
     placement: Props["placement"];
     showTail: Props["showTail"];
+    portal: Props["portal"];
 }>;
 /**
  * Popovers provide additional information that is related to a particular
@@ -151,6 +166,7 @@ export default class Popover extends React.Component<Props, State> {
     renderContent(uniqueId: string): PopoverContents;
     renderPopper(uniqueId: string): React.ReactNode;
     getHost(): Element | null | undefined;
+    renderPortal(uniqueId: string, opened: boolean): React.ReactNode;
     render(): React.ReactNode;
 }
 export {};

package/dist/es/index.js

@@ -72,11 +72,13 @@ class PopoverDialog extends React.Component {
       style,
       showTail,
       "aria-describedby": ariaDescribedby,
-      "aria-labelledby": ariaLabelledBy
+      "aria-labelledby": ariaLabelledBy,
+      "aria-label": ariaLabel
     } = this.props;
     const contentProps = children.props;
     const color = contentProps.emphasized ? "blue" : contentProps.color;
     return React.createElement(React.Fragment, null, React.createElement(View, {
+      "aria-label": ariaLabel,
       "aria-describedby": ariaDescribedby,
       "aria-labelledby": ariaLabelledBy,
       id: id,
@@ -122,6 +124,49 @@ function isFocusable(element) {
   return element.matches(FOCUSABLE_ELEMENTS);
 }
 
+class PopoverEventListener extends React.Component {
+  constructor(...args) {
+    super(...args);
+    this.state = {
+      isFirstClick: true
+    };
+    this._handleKeyup = e => {
+      if (e.key === "Escape") {
+        e.preventDefault();
+        e.stopPropagation();
+        this.props.onClose(true);
+      }
+    };
+    this._handleClick = e => {
+      var _this$props$contentRe;
+      if (this.state.isFirstClick) {
+        this.setState({
+          isFirstClick: false
+        });
+        return;
+      }
+      const node = ReactDOM.findDOMNode((_this$props$contentRe = this.props.contentRef) == null ? void 0 : _this$props$contentRe.current);
+      if (node && !node.contains(e.target)) {
+        e.preventDefault();
+        e.stopPropagation();
+        const shouldReturnFocus = !isFocusable(e.target);
+        this.props.onClose(shouldReturnFocus);
+      }
+    };
+  }
+  componentDidMount() {
+    window.addEventListener("keyup", this._handleKeyup);
+    window.addEventListener("click", this._handleClick);
+  }
+  componentWillUnmount() {
+    window.removeEventListener("keyup", this._handleKeyup);
+    window.removeEventListener("click", this._handleClick);
+  }
+  render() {
+    return null;
+  }
+}
+
 class InitialFocus extends React.Component {
   constructor(...args) {
     super(...args);
@@ -327,49 +372,6 @@ class FocusManager extends React.Component {
   }
 }
 
-class PopoverEventListener extends React.Component {
-  constructor(...args) {
-    super(...args);
-    this.state = {
-      isFirstClick: true
-    };
-    this._handleKeyup = e => {
-      if (e.key === "Escape") {
-        e.preventDefault();
-        e.stopPropagation();
-        this.props.onClose(true);
-      }
-    };
-    this._handleClick = e => {
-      var _this$props$contentRe;
-      if (this.state.isFirstClick) {
-        this.setState({
-          isFirstClick: false
-        });
-        return;
-      }
-      const node = ReactDOM.findDOMNode((_this$props$contentRe = this.props.contentRef) == null ? void 0 : _this$props$contentRe.current);
-      if (node && !node.contains(e.target)) {
-        e.preventDefault();
-        e.stopPropagation();
-        const shouldReturnFocus = !isFocusable(e.target);
-        this.props.onClose(shouldReturnFocus);
-      }
-    };
-  }
-  componentDidMount() {
-    window.addEventListener("keyup", this._handleKeyup);
-    window.addEventListener("click", this._handleClick);
-  }
-  componentWillUnmount() {
-    window.removeEventListener("keyup", this._handleKeyup);
-    window.removeEventListener("click", this._handleClick);
-  }
-  render() {
-    return null;
-  }
-}
-
 class Popover extends React.Component {
   constructor(...args) {
     super(...args);
@@ -443,30 +445,55 @@ class Popover extends React.Component {
     const {
       initialFocusId,
       placement,
-      showTail
+      showTail,
+      portal,
+      "aria-label": ariaLabel
     } = this.props;
     const {
       anchorElement
     } = this.state;
-    return React.createElement(FocusManager, {
-      anchorElement: anchorElement,
-      initialFocusId: initialFocusId
-    }, React.createElement(TooltipPopper, {
+    const ariaDescribedBy = ariaLabel ? undefined : `${uniqueId}-content`;
+    const ariaLabelledBy = ariaLabel ? undefined : `${uniqueId}-title`;
+    const popperContent = React.createElement(TooltipPopper, {
       anchorElement: anchorElement,
       placement: placement
     }, props => React.createElement(PopoverDialog, _extends({}, props, {
-      "aria-describedby": `${uniqueId}-content`,
-      "aria-labelledby": `${uniqueId}-title`,
+      "aria-label": ariaLabel,
+      "aria-describedby": ariaDescribedBy,
+      "aria-labelledby": ariaLabelledBy,
       id: uniqueId,
       onUpdate: placement => this.setState({
         placement
       }),
       showTail: showTail
-    }), this.renderContent(uniqueId))));
+    }), this.renderContent(uniqueId)));
+    if (portal) {
+      return React.createElement(FocusManager, {
+        anchorElement: anchorElement,
+        initialFocusId: initialFocusId
+      }, popperContent);
+    } else {
+      return React.createElement(InitialFocus, {
+        initialFocusId: initialFocusId
+      }, popperContent);
+    }
   }
   getHost() {
     return maybeGetPortalMountedModalHostElement(this.state.anchorElement) || document.body;
   }
+  renderPortal(uniqueId, opened) {
+    if (!opened) {
+      return null;
+    }
+    const {
+      portal
+    } = this.props;
+    const popperHost = this.getHost();
+    if (portal && popperHost) {
+      return ReactDOM.createPortal(this.renderPopper(uniqueId), popperHost);
+    }
+    return this.renderPopper(uniqueId);
+  }
   render() {
     const {
       children,
@@ -477,7 +504,6 @@ class Popover extends React.Component {
       opened,
       placement
     } = this.state;
-    const popperHost = this.getHost();
     return React.createElement(PopoverContext.Provider, {
       value: {
         close: this.handleClose,
@@ -492,7 +518,7 @@ class Popover extends React.Component {
       "aria-controls": uniqueId,
       "aria-expanded": opened ? "true" : "false",
       onClick: this.handleOpen
-    }, children), popperHost && opened && ReactDOM.createPortal(this.renderPopper(uniqueId), popperHost))), dismissEnabled && opened && React.createElement(PopoverEventListener, {
+    }, children), this.renderPortal(uniqueId, opened))), dismissEnabled && opened && React.createElement(PopoverEventListener, {
       onClose: this.handleClose,
       contentRef: this.contentRef
     }));
@@ -500,7 +526,8 @@ class Popover extends React.Component {
 }
 Popover.defaultProps = {
   placement: "top",
-  showTail: true
+  showTail: true,
+  portal: true
 };
 
 class CloseButton extends React.Component {

package/dist/index.js

@@ -102,11 +102,13 @@ class PopoverDialog extends React__namespace.Component {
       style,
       showTail,
       "aria-describedby": ariaDescribedby,
-      "aria-labelledby": ariaLabelledBy
+      "aria-labelledby": ariaLabelledBy,
+      "aria-label": ariaLabel
     } = this.props;
     const contentProps = children.props;
     const color = contentProps.emphasized ? "blue" : contentProps.color;
     return React__namespace.createElement(React__namespace.Fragment, null, React__namespace.createElement(wonderBlocksCore.View, {
+      "aria-label": ariaLabel,
       "aria-describedby": ariaDescribedby,
       "aria-labelledby": ariaLabelledBy,
       id: id,
@@ -152,6 +154,49 @@ function isFocusable(element) {
   return element.matches(FOCUSABLE_ELEMENTS);
 }
 
+class PopoverEventListener extends React__namespace.Component {
+  constructor(...args) {
+    super(...args);
+    this.state = {
+      isFirstClick: true
+    };
+    this._handleKeyup = e => {
+      if (e.key === "Escape") {
+        e.preventDefault();
+        e.stopPropagation();
+        this.props.onClose(true);
+      }
+    };
+    this._handleClick = e => {
+      var _this$props$contentRe;
+      if (this.state.isFirstClick) {
+        this.setState({
+          isFirstClick: false
+        });
+        return;
+      }
+      const node = ReactDOM__namespace.findDOMNode((_this$props$contentRe = this.props.contentRef) == null ? void 0 : _this$props$contentRe.current);
+      if (node && !node.contains(e.target)) {
+        e.preventDefault();
+        e.stopPropagation();
+        const shouldReturnFocus = !isFocusable(e.target);
+        this.props.onClose(shouldReturnFocus);
+      }
+    };
+  }
+  componentDidMount() {
+    window.addEventListener("keyup", this._handleKeyup);
+    window.addEventListener("click", this._handleClick);
+  }
+  componentWillUnmount() {
+    window.removeEventListener("keyup", this._handleKeyup);
+    window.removeEventListener("click", this._handleClick);
+  }
+  render() {
+    return null;
+  }
+}
+
 class InitialFocus extends React__namespace.Component {
   constructor(...args) {
     super(...args);
@@ -357,49 +402,6 @@ class FocusManager extends React__namespace.Component {
   }
 }
 
-class PopoverEventListener extends React__namespace.Component {
-  constructor(...args) {
-    super(...args);
-    this.state = {
-      isFirstClick: true
-    };
-    this._handleKeyup = e => {
-      if (e.key === "Escape") {
-        e.preventDefault();
-        e.stopPropagation();
-        this.props.onClose(true);
-      }
-    };
-    this._handleClick = e => {
-      var _this$props$contentRe;
-      if (this.state.isFirstClick) {
-        this.setState({
-          isFirstClick: false
-        });
-        return;
-      }
-      const node = ReactDOM__namespace.findDOMNode((_this$props$contentRe = this.props.contentRef) == null ? void 0 : _this$props$contentRe.current);
-      if (node && !node.contains(e.target)) {
-        e.preventDefault();
-        e.stopPropagation();
-        const shouldReturnFocus = !isFocusable(e.target);
-        this.props.onClose(shouldReturnFocus);
-      }
-    };
-  }
-  componentDidMount() {
-    window.addEventListener("keyup", this._handleKeyup);
-    window.addEventListener("click", this._handleClick);
-  }
-  componentWillUnmount() {
-    window.removeEventListener("keyup", this._handleKeyup);
-    window.removeEventListener("click", this._handleClick);
-  }
-  render() {
-    return null;
-  }
-}
-
 class Popover extends React__namespace.Component {
   constructor(...args) {
     super(...args);
@@ -473,30 +475,55 @@ class Popover extends React__namespace.Component {
     const {
       initialFocusId,
       placement,
-      showTail
+      showTail,
+      portal,
+      "aria-label": ariaLabel
     } = this.props;
     const {
       anchorElement
     } = this.state;
-    return React__namespace.createElement(FocusManager, {
-      anchorElement: anchorElement,
-      initialFocusId: initialFocusId
-    }, React__namespace.createElement(wonderBlocksTooltip.TooltipPopper, {
+    const ariaDescribedBy = ariaLabel ? undefined : `${uniqueId}-content`;
+    const ariaLabelledBy = ariaLabel ? undefined : `${uniqueId}-title`;
+    const popperContent = React__namespace.createElement(wonderBlocksTooltip.TooltipPopper, {
       anchorElement: anchorElement,
       placement: placement
     }, props => React__namespace.createElement(PopoverDialog, _extends__default["default"]({}, props, {
-      "aria-describedby": `${uniqueId}-content`,
-      "aria-labelledby": `${uniqueId}-title`,
+      "aria-label": ariaLabel,
+      "aria-describedby": ariaDescribedBy,
+      "aria-labelledby": ariaLabelledBy,
       id: uniqueId,
       onUpdate: placement => this.setState({
         placement
       }),
       showTail: showTail
-    }), this.renderContent(uniqueId))));
+    }), this.renderContent(uniqueId)));
+    if (portal) {
+      return React__namespace.createElement(FocusManager, {
+        anchorElement: anchorElement,
+        initialFocusId: initialFocusId
+      }, popperContent);
+    } else {
+      return React__namespace.createElement(InitialFocus, {
+        initialFocusId: initialFocusId
+      }, popperContent);
+    }
   }
   getHost() {
     return wonderBlocksModal.maybeGetPortalMountedModalHostElement(this.state.anchorElement) || document.body;
   }
+  renderPortal(uniqueId, opened) {
+    if (!opened) {
+      return null;
+    }
+    const {
+      portal
+    } = this.props;
+    const popperHost = this.getHost();
+    if (portal && popperHost) {
+      return ReactDOM__namespace.createPortal(this.renderPopper(uniqueId), popperHost);
+    }
+    return this.renderPopper(uniqueId);
+  }
   render() {
     const {
       children,
@@ -507,7 +534,6 @@ class Popover extends React__namespace.Component {
       opened,
       placement
     } = this.state;
-    const popperHost = this.getHost();
     return React__namespace.createElement(PopoverContext.Provider, {
       value: {
         close: this.handleClose,
@@ -522,7 +548,7 @@ class Popover extends React__namespace.Component {
       "aria-controls": uniqueId,
       "aria-expanded": opened ? "true" : "false",
       onClick: this.handleOpen
-    }, children), popperHost && opened && ReactDOM__namespace.createPortal(this.renderPopper(uniqueId), popperHost))), dismissEnabled && opened && React__namespace.createElement(PopoverEventListener, {
+    }, children), this.renderPortal(uniqueId, opened))), dismissEnabled && opened && React__namespace.createElement(PopoverEventListener, {
       onClose: this.handleClose,
       contentRef: this.contentRef
     }));
@@ -530,7 +556,8 @@ class Popover extends React__namespace.Component {
 }
 Popover.defaultProps = {
   placement: "top",
-  showTail: true
+  showTail: true,
+  portal: true
 };
 
 class CloseButton extends React__namespace.Component {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanacademy/wonder-blocks-popover",
-  "version": "3.2.8",
+  "version": "3.2.10",
   "design": "v1",
   "publishConfig": {
     "access": "public"
@@ -20,7 +20,7 @@
     "@khanacademy/wonder-blocks-icon-button": "^5.3.3",
     "@khanacademy/wonder-blocks-modal": "^5.1.8",
     "@khanacademy/wonder-blocks-tokens": "^1.3.1",
-    "@khanacademy/wonder-blocks-tooltip": "^2.3.7",
+    "@khanacademy/wonder-blocks-tooltip": "^2.3.8",
     "@khanacademy/wonder-blocks-typography": "^2.1.14"
   },
   "peerDependencies": {

package/src/components/__tests__/popover.test.tsx

@@ -583,6 +583,40 @@ describe("Popover", () => {
             ).toBeInTheDocument();
         });
 
+        it("should announce a popover correctly by reading the aria label", async () => {
+            // Arrange
+            render(
+                <Popover
+                    onClose={jest.fn()}
+                    aria-label="Popover Aria Label"
+                    content={
+                        <PopoverContentCore>
+                            <button data-close-button onClick={close}>
+                                Close Popover
+                            </button>
+                        </PopoverContentCore>
+                    }
+                >
+                    <Button>Open default popover</Button>
+                </Popover>,
+            );
+
+            // Act
+            // Open the popover
+            const openButton = await screen.findByRole("button", {
+                name: "Open default popover",
+            });
+
+            await userEvent.click(openButton);
+            const popover = await screen.findByRole("dialog");
+
+            // Assert
+
+            expect(popover).toHaveAttribute("aria-label", "Popover Aria Label");
+            expect(popover).not.toHaveAttribute("aria-labelledby");
+            expect(popover).not.toHaveAttribute("aria-describedby");
+        });
+
         it("should correctly describe the popover content core's aria label", async () => {
             // Arrange
             render(
@@ -621,14 +655,15 @@ describe("Popover", () => {
         });
     });
 
-    describe("keyboard navigation", () => {
-        it("should move focus to the first focusable element after popover is open", async () => {
+    describe.each([true, false])("keyboard navigation", (portal) => {
+        it(`when portal=${portal}, should move focus to the first focusable element after popover is open`, async () => {
             // Arrange
             render(
                 <>
                     <Button>Prev focusable element outside</Button>
                     <Popover
                         onClose={jest.fn()}
+                        portal={portal}
                         content={
                             <PopoverContent
                                 title="Popover title"
@@ -667,13 +702,14 @@ describe("Popover", () => {
             ).toHaveFocus();
         });
 
-        it("should allow flowing focus correctly even if the popover remains open", async () => {
+        it(`when portal=${portal}, should allow flowing focus correctly even if the popover remains open`, async () => {
             // Arrange
             render(
                 <>
                     <Button>Prev focusable element outside</Button>
                     <Popover
                         onClose={jest.fn()}
+                        portal={portal}
                         content={
                             <PopoverContent
                                 title="Popover title"
@@ -709,13 +745,14 @@ describe("Popover", () => {
             ).toHaveFocus();
         });
 
-        it("should allow circular navigation when the popover is open", async () => {
+        it(`when portal=${portal}, should allow circular navigation when the popover is open`, async () => {
             // Arrange
             render(
                 <>
                     <Button>Prev focusable element outside</Button>
                     <Popover
                         onClose={jest.fn()}
+                        portal={portal}
                         content={
                             <PopoverContent
                                 title="Popover title"
@@ -757,13 +794,14 @@ describe("Popover", () => {
             ).toHaveFocus();
         });
 
-        it("should allow navigating backwards when the popover is open", async () => {
+        it(`when portal=${portal}, should allow navigating backwards when the popover is open`, async () => {
             // Arrange
             render(
                 <>
                     <Button>Prev focusable element outside</Button>
                     <Popover
                         onClose={jest.fn()}
+                        portal={portal}
                         content={
                             <PopoverContent
                                 title="Popover title"

package/src/components/popover-dialog.tsx

@@ -78,6 +78,7 @@ export default class PopoverDialog extends React.Component<Props> {
             showTail,
             "aria-describedby": ariaDescribedby,
             "aria-labelledby": ariaLabelledBy,
+            "aria-label": ariaLabel,
         } = this.props;
 
         const contentProps = children.props as any;
@@ -90,6 +91,7 @@ export default class PopoverDialog extends React.Component<Props> {
         return (
             <React.Fragment>
                 <View
+                    aria-label={ariaLabel}
                     aria-describedby={ariaDescribedby}
                     aria-labelledby={ariaLabelledBy}
                     id={id}