@khanacademy/wonder-blocks-popover 3.2.15 → 3.2.16

package/src/components/popover-event-listener.ts

@@ -1,96 +0,0 @@
-import * as React from "react";
-import * as ReactDOM from "react-dom";
-import {isFocusable} from "../util/util";
-
-import PopoverContent from "./popover-content";
-import PopoverContentCore from "./popover-content-core";
-
-type Props = {
-    /**
-     * Called when `esc` is pressed
-     */
-    onClose: (shouldReturnFocus: boolean) => unknown;
-    /**
-     * Popover Content ref.
-     * Will close the popover when clicking outside this element.
-     */
-    contentRef?: React.RefObject<PopoverContentCore | PopoverContent>;
-};
-
-type State = {
-    /**
-     * Tracks the first click triggered by the click event listener.
-     */
-    isFirstClick: boolean;
-};
-
-/**
- * A component that, when mounted, calls `onClose` when certain events occur.
- * This includes when pressing Escape or clicking outside the Popover.
- * @see @khanacademy/wonder-blocks-modal/components/modal-launcher.js
- */
-export default class PopoverEventListener extends React.Component<
-    Props,
-    State
-> {
-    state: State = {
-        isFirstClick: true,
-    };
-
-    componentDidMount() {
-        window.addEventListener("keyup", this._handleKeyup);
-        window.addEventListener("click", this._handleClick);
-    }
-
-    componentWillUnmount() {
-        window.removeEventListener("keyup", this._handleKeyup);
-        window.removeEventListener("click", this._handleClick);
-    }
-
-    _handleKeyup: (e: KeyboardEvent) => void = (e) => {
-        // We check the key as that's keyboard layout agnostic and also avoids
-        // the minefield of deprecated number type properties like keyCode and
-        // which, with the replacement code, which uses a string instead.
-        if (e.key === "Escape") {
-            // Stop the event going any further.
-            // For cancellation events, like the Escape key, we generally should
-            // air on the side of caution and only allow it to cancel one thing.
-            // So, it's polite for us to stop propagation of the event.
-            // Otherwise, we end up with UX where one Escape key press
-            // unexpectedly cancels multiple things.
-            e.preventDefault();
-            e.stopPropagation();
-            // In the case of the Escape key, we should return focus to the
-            // trigger button.
-            this.props.onClose(true);
-        }
-    };
-
-    _handleClick: (e: MouseEvent) => void = (e) => {
-        // Prevents the problem where clicking the trigger button
-        // triggers a click event and immediately closes the popover.
-        if (this.state.isFirstClick) {
-            this.setState({isFirstClick: false});
-            return;
-        }
-
-        const node = ReactDOM.findDOMNode(this.props.contentRef?.current);
-        if (node && !node.contains(e.target as any)) {
-            // Stop the event going any further.
-            // Only allow click to cancel one thing at a time.
-            e.preventDefault();
-            e.stopPropagation();
-
-            // Determine if the focus must go to a focusable/interactive
-            // element.
-            const shouldReturnFocus = !isFocusable(e.target as any);
-            // If that's the case, we need to prevent the default behavior of
-            // returning the focus to the trigger button.
-            this.props.onClose(shouldReturnFocus);
-        }
-    };
-
-    render(): React.ReactElement | null {
-        return null;
-    }
-}

package/src/components/popover.tsx

@@ -1,410 +0,0 @@
-import * as React from "react";
-import * as ReactDOM from "react-dom";
-
-import {IDProvider} from "@khanacademy/wonder-blocks-core";
-import {TooltipPopper} from "@khanacademy/wonder-blocks-tooltip";
-import {maybeGetPortalMountedModalHostElement} from "@khanacademy/wonder-blocks-modal";
-
-import type {AriaProps} from "@khanacademy/wonder-blocks-core";
-import type {
-    Placement,
-    PopperElementProps,
-} from "@khanacademy/wonder-blocks-tooltip";
-import type {RootBoundary} from "@popperjs/core";
-
-import PopoverContent from "./popover-content";
-import PopoverContentCore from "./popover-content-core";
-import PopoverContext from "./popover-context";
-import PopoverAnchor from "./popover-anchor";
-import PopoverDialog from "./popover-dialog";
-import PopoverEventListener from "./popover-event-listener";
-import InitialFocus from "./initial-focus";
-import FocusManager from "./focus-manager";
-
-type PopoverContents =
-    | React.ReactElement<React.ComponentProps<typeof PopoverContent>>
-    | React.ReactElement<React.ComponentProps<typeof PopoverContentCore>>;
-
-type Props = AriaProps &
-    Readonly<{
-        /**
-         * The element that triggers the popover. This element will be used to
-         * position the popover. It can be either a Node or a function using the
-         * children-as-function pattern to pass an open function for use anywhere
-         * within children. The latter provides a lot of flexibility in terms of
-         * what actions may trigger the `Popover` to launch the popover dialog.
-         */
-        children:
-            | React.ReactElement<any>
-            | ((arg1: {open: () => void}) => React.ReactElement<any>);
-        /**
-         * The content of the popover. You can either use
-         * [PopoverContent](#PopoverContent) with one of the pre-defined variants,
-         * or include your own custom content using
-         * [PopoverContentCore](#PopoverContentCore directly.
-         *
-         * If the popover needs to close itself, the close function provided to this
-         * callback can be called to close the popover.
-         */
-        content:
-            | PopoverContents
-            | ((arg1: {close: () => void}) => PopoverContents);
-        /**
-         * Where the popover should try to appear in relation to the trigger element.
-         */
-        placement: Placement;
-        /**
-         * When enabled, user can hide the popover content by pressing the `esc` key
-         * or clicking/tapping outside of it.
-         */
-        dismissEnabled?: boolean;
-        /**
-         * The unique identifier to give to the popover. Provide this in cases
-         * where you want to override the default accessibility solution. This
-         * identifier will be applied to the popover title and content.
-         *
-         * This is also used as a prefix to the IDs of the popover's elements.
-         *
-         * For example, if you pass `"my-popover"` as the ID, the popover title
-         * will have the ID `"my-popover-title"` and the popover content will
-         * have the ID `"my-popover-content"`.
-         *
-         */
-        id?: string;
-        /**
-         * The selector for the element that will be focused after the popover
-         * dialog closes. When not set, the element that triggered the popover
-         * will be used.
-         */
-        closedFocusId?: string;
-        /**
-         * The selector for the element that will be focused when the popover
-         * content shows. When not set, the first focusable element within the
-         * popover content will be used.
-         */
-        initialFocusId?: string;
-        /**
-         * Renders the popover when true, renders nothing when false.
-         *
-         * Using this prop makes the component behave as a controlled component. The
-         * parent is responsible for managing the opening/closing of the popover
-         * when using this prop.
-         */
-        opened?: boolean;
-        /**
-         * Called when the popover closes
-         */
-        onClose?: () => unknown;
-        /**
-         * Test ID used for e2e testing.
-         */
-        testId?: string;
-        /**
-         * 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;
-        /**
-         * Optional property to set what the root boundary is for the popper behavior.
-         * This is set to "viewport" by default, causing the popper to be positioned based
-         * on the user's viewport. If set to "document", it will position itself based
-         * on where there is available room within the document body.
-         */
-        rootBoundary?: RootBoundary;
-    }>;
-
-type State = Readonly<{
-    /**
-     * Keeps a reference of the dialog state
-     */
-    opened: boolean;
-    /**
-     * Anchor element DOM reference
-     */
-    anchorElement?: HTMLElement;
-    /**
-     * Current popper placement
-     */
-    placement: Placement;
-}>;
-
-type DefaultProps = Readonly<{
-    placement: Props["placement"];
-    showTail: Props["showTail"];
-    portal: Props["portal"];
-    rootBoundary: Props["rootBoundary"];
-}>;
-
-/**
- * Popovers provide additional information that is related to a particular
- * element and/or content. They can include text, links, icons and
- * illustrations. The main difference with `Tooltip` is that they must be
- * dismissed by clicking an element.
- *
- * This component uses the `PopoverPopper` component to position the
- * `PopoverContentCore` component according to the children it is wrapping.
- *
- * ### Usage
- *
- * ```jsx
- * import {Popover, PopoverContent} from "@khanacademy/wonder-blocks-popover";
- *
- * <Popover
- *  onClose={() => {}}
- *  content={
- *      <PopoverContent title="Title" content="Some content" closeButtonVisible />
- *  }>
- *      {({ open }) => <Button onClick={open}>Open popover</Button>}
- *  </Popover>
- * ```
- */
-export default class Popover extends React.Component<Props, State> {
-    static defaultProps: DefaultProps = {
-        placement: "top",
-        showTail: true,
-        portal: true,
-        rootBoundary: "viewport",
-    };
-
-    /**
-     * Used to sync the `opened` state when Popover acts as a controlled
-     * component
-     */
-    static getDerivedStateFromProps(
-        props: Props,
-        state: State,
-    ): Partial<State> | null | undefined {
-        return {
-            opened:
-                typeof props.opened === "boolean" ? props.opened : state.opened,
-        };
-    }
-
-    state: State = {
-        opened: !!this.props.opened,
-        placement: this.props.placement,
-    };
-
-    /**
-     * Popover content ref
-     */
-    contentRef: React.RefObject<PopoverContent | PopoverContentCore> =
-        React.createRef();
-
-    /**
-     * Returns focus to a given element.
-     */
-    maybeReturnFocus = () => {
-        const {anchorElement} = this.state;
-        const {closedFocusId} = this.props;
-
-        // Focus on the specified element after dismissing the popover.
-        if (closedFocusId) {
-            const focusElement = ReactDOM.findDOMNode(
-                document.getElementById(closedFocusId),
-            ) as any;
-
-            focusElement?.focus();
-            return;
-        }
-
-        // If no element is specified, focus on the element that triggered the
-        // popover.
-        if (anchorElement) {
-            anchorElement.focus();
-        }
-    };
-
-    /**
-     * Popover dialog closed
-     */
-    handleClose: (shouldReturnFocus?: boolean) => void = (
-        shouldReturnFocus = true,
-    ) => {
-        this.setState({opened: false}, () => {
-            this.props.onClose?.();
-
-            if (shouldReturnFocus) {
-                this.maybeReturnFocus();
-            }
-        });
-    };
-
-    /**
-     * Popover dialog opened
-     */
-    handleOpen: () => void = () => {
-        if (this.props.dismissEnabled && this.state.opened) {
-            this.handleClose(true);
-        } else {
-            this.setState({opened: true});
-        }
-    };
-
-    updateRef = (actualRef?: HTMLElement) => {
-        if (actualRef && this.state.anchorElement !== actualRef) {
-            this.setState({
-                anchorElement: actualRef,
-            });
-        }
-    };
-
-    renderContent(uniqueId: string): PopoverContents {
-        const {content} = this.props;
-
-        const popoverContents: PopoverContents =
-            typeof content === "function"
-                ? content({
-                      close: this.handleClose,
-                  })
-                : content;
-
-        // @ts-expect-error: TS2769 - No overload matches this call.
-        return React.cloneElement(popoverContents, {
-            ref: this.contentRef,
-            // internal prop: only injected by Popover
-            // This allows us to announce the popover content when it is opened.
-            uniqueId,
-        });
-    }
-
-    renderPopper(uniqueId: string): React.ReactNode {
-        const {
-            initialFocusId,
-            placement,
-            showTail,
-            portal,
-            "aria-label": ariaLabel,
-            "aria-describedby": ariaDescribedBy,
-            rootBoundary,
-        } = this.props;
-        const {anchorElement} = this.state;
-
-        const describedBy = ariaDescribedBy || `${uniqueId}-content`;
-
-        const ariaLabelledBy = ariaLabel ? undefined : `${uniqueId}-title`;
-
-        const popperContent = (
-            <TooltipPopper
-                anchorElement={anchorElement}
-                placement={placement}
-                rootBoundary={rootBoundary}
-            >
-                {(props: PopperElementProps) => (
-                    <PopoverDialog
-                        {...props}
-                        aria-label={ariaLabel}
-                        aria-describedby={describedBy}
-                        aria-labelledby={ariaLabelledBy}
-                        id={uniqueId}
-                        onUpdate={(placement) => this.setState({placement})}
-                        showTail={showTail}
-                    >
-                        {this.renderContent(uniqueId)}
-                    </PopoverDialog>
-                )}
-            </TooltipPopper>
-        );
-
-        if (portal) {
-            return (
-                <FocusManager
-                    anchorElement={anchorElement}
-                    initialFocusId={initialFocusId}
-                >
-                    {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 {
-        // If we are in a modal, we find where we should be portalling the
-        // popover by using the helper function from the modal package on the
-        // trigger element. If we are not in a modal, we use body as the
-        // location to portal to.
-        return (
-            maybeGetPortalMountedModalHostElement(this.state.anchorElement) ||
-            document.body
-        );
-    }
-
-    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;
-
-        return (
-            <PopoverContext.Provider
-                value={{
-                    close: this.handleClose,
-                    placement: placement,
-                }}
-            >
-                <IDProvider id={id} scope="popover">
-                    {(uniqueId) => (
-                        <React.Fragment>
-                            <PopoverAnchor
-                                anchorRef={this.updateRef}
-                                id={`${uniqueId}-anchor`}
-                                aria-controls={uniqueId}
-                                aria-expanded={opened ? "true" : "false"}
-                                onClick={this.handleOpen}
-                            >
-                                {children}
-                            </PopoverAnchor>
-                            {this.renderPortal(uniqueId, opened)}
-                        </React.Fragment>
-                    )}
-                </IDProvider>
-
-                {dismissEnabled && opened && (
-                    <PopoverEventListener
-                        onClose={this.handleClose}
-                        contentRef={this.contentRef}
-                    />
-                )}
-            </PopoverContext.Provider>
-        );
-    }
-}

package/src/index.ts

@@ -1,5 +0,0 @@
-import Popover from "./components/popover";
-import PopoverContent from "./components/popover-content";
-import PopoverContentCore from "./components/popover-content-core";
-
-export {Popover, PopoverContent, PopoverContentCore};

package/src/util/__tests__/util.test.tsx

@@ -1,38 +0,0 @@
-import * as React from "react";
-import {render, screen} from "@testing-library/react";
-import {isFocusable} from "../util";
-
-describe("isFocusable", () => {
-    it("should mark a button as focusable", () => {
-        // Arrange
-        render(<button>Open popover</button>);
-
-        // Act
-        const result = isFocusable(screen.getByRole("button"));
-
-        // Assert
-        expect(result).toBe(true);
-    });
-
-    it("should mark a div as non-focusable", () => {
-        // Arrange
-        render(<div>placeholder</div>);
-
-        // Act
-        const result = isFocusable(screen.getByText("placeholder"));
-
-        // Assert
-        expect(result).toBe(false);
-    });
-
-    it("should mark a div with tabIndex greater than -1 as focusable", () => {
-        // Arrange
-        render(<div tabIndex={0}>placeholder</div>);
-
-        // Act
-        const result = isFocusable(screen.getByText("placeholder"));
-
-        // Assert
-        expect(result).toBe(true);
-    });
-});

package/src/util/util.ts

@@ -1,20 +0,0 @@
-/**
- * List of elements that can be focused
- * @see https://www.w3.org/TR/html5/editing.html#can-be-focused
- */
-const FOCUSABLE_ELEMENTS =
-    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
-
-export function findFocusableNodes(
-    root: HTMLElement | Document,
-): Array<HTMLElement> {
-    return Array.from(root.querySelectorAll(FOCUSABLE_ELEMENTS));
-}
-
-/**
- * Checks if an element is focusable
- * @see https://html.spec.whatwg.org/multipage/interaction.html#focusable-area
- */
-export function isFocusable(element: HTMLElement): boolean {
-    return element.matches(FOCUSABLE_ELEMENTS);
-}

package/tsconfig-build.json

@@ -1,17 +0,0 @@
-{
-    "exclude": ["dist"],
-    "extends": "../tsconfig-shared.json",
-    "compilerOptions": {
-        "outDir": "./dist",
-        "rootDir": "src",
-    },
-    "references": [
-        {"path": "../wonder-blocks-core/tsconfig-build.json"},
-        {"path": "../wonder-blocks-icon/tsconfig-build.json"},
-        {"path": "../wonder-blocks-icon-button/tsconfig-build.json"},
-        {"path": "../wonder-blocks-modal/tsconfig-build.json"},
-        {"path": "../wonder-blocks-tokens/tsconfig-build.json"},
-        {"path": "../wonder-blocks-tooltip/tsconfig-build.json"},
-        {"path": "../wonder-blocks-typography/tsconfig-build.json"},
-    ]
-}