@khanacademy/wonder-blocks-modal 5.1.11 → 5.1.13

package/src/components/modal-header.tsx

@@ -1,194 +0,0 @@
-import * as React from "react";
-import {Breadcrumbs} from "@khanacademy/wonder-blocks-breadcrumbs";
-import {View} from "@khanacademy/wonder-blocks-core";
-import {HeadingMedium, LabelSmall} from "@khanacademy/wonder-blocks-typography";
-import {
-    ThemedStylesFn,
-    useScopedTheme,
-    useStyles,
-} from "@khanacademy/wonder-blocks-theming";
-import {
-    ModalDialogThemeContext,
-    ModalDialogThemeContract,
-} from "../themes/themed-modal-dialog";
-
-type Common = {
-    /**
-     * The main title rendered in larger bold text.
-     */
-    title: string;
-    /**
-     * Whether to display the "light" version of this component instead, for
-     * use when the item is used on a dark background.
-     */
-    light: boolean;
-    /**
-     * An id to provide a selector for the title element.
-     */
-    titleId: string;
-    /**
-     * Test ID used for e2e testing.
-     *
-     * In this case, this component is internal, so `testId` is composed with
-     * the `testId` passed down from the Dialog variant + a suffix to scope it
-     * to this component.
-     *
-     * @example
-     * For testId="some-random-id"
-     * The result will be: `some-random-id-modal-header`
-     */
-    testId?: string;
-};
-
-type WithSubtitle = Common & {
-    /**
-     * The dialog subtitle.
-     */
-    subtitle: string;
-};
-
-type WithBreadcrumbs = Common & {
-    /**
-     * Adds a breadcrumb-trail, appearing in the ModalHeader, above the title.
-     */
-    breadcrumbs: React.ReactElement<React.ComponentProps<typeof Breadcrumbs>>;
-};
-
-type Props = Common | WithSubtitle | WithBreadcrumbs;
-
-/**
- * This is a helper component that is never rendered by itself. It is always
- * pinned to the top of the dialog, is responsive using the same behavior as its
- * parent dialog, and has the following properties:
- * - title
- * - breadcrumb OR subtitle, but not both.
- *
- * **Accessibility notes:**
- *
- * - By default (e.g. using [OnePaneDialog](/#onepanedialog)), `titleId` is
- *   populated automatically by the parent container.
- * - If there is a custom Dialog implementation (e.g. `TwoPaneDialog`), the
- *   ModalHeader doesn’t have to have the `titleId` prop however this is
- *   recommended. It should match the `aria-labelledby` prop of the
- *   [ModalDialog](/#modaldialog) component. If you want to see an example of
- *   how to generate this ID, check [IDProvider](/#idprovider).
- *
- * **Implementation notes:**
- *
- * If you are creating a custom Dialog, make sure to follow these guidelines:
- * - Make sure to include it as part of [ModalPanel](/#modalpanel) by using the
- *   `header` prop.
- * - Add a title (required).
- * - Optionally add a subtitle or breadcrumbs.
- * - We encourage you to add `titleId` (see Accessibility notes).
- * - If the `ModalPanel` has a dark background, make sure to set `light` to
- *   `false`.
- * - If you need to create e2e tests, make sure to pass a `testId` prop and
- *   add a sufix to scope the testId to this component: e.g.
- *   `some-random-id-ModalHeader`. This scope will also be passed to the title
- *   and subtitle elements: e.g. `some-random-id-ModalHeader-title`.
- *
- * Example:
- *
- * ```js
- * <ModalHeader
- *      title="Sidebar using ModalHeader"
- *      subtitle="subtitle"
- *      titleId="uniqueTitleId"
- *      light={false}
- *  />
- * ```
- */
-export default function ModalHeader(props: Props) {
-    const {
-        // @ts-expect-error [FEI-5019] - TS2339 - Property 'breadcrumbs' does not exist on type 'Readonly<Props> & Readonly<{ children?: ReactNode; }>'.
-        breadcrumbs = undefined,
-        light,
-        // @ts-expect-error [FEI-5019] - TS2339 - Property 'subtitle' does not exist on type 'Readonly<Props> & Readonly<{ children?: ReactNode; }>'.
-        subtitle = undefined,
-        testId,
-        title,
-        titleId,
-    } = props;
-
-    if (subtitle && breadcrumbs) {
-        throw new Error("'subtitle' and 'breadcrumbs' can't be used together");
-    }
-
-    const {theme} = useScopedTheme(ModalDialogThemeContext);
-    const styles = useStyles(themedStylesFn, theme);
-
-    return (
-        <View style={[styles.header, !light && styles.dark]} testId={testId}>
-            {breadcrumbs && (
-                <View style={styles.breadcrumbs}>{breadcrumbs}</View>
-            )}
-            <HeadingMedium
-                style={styles.title}
-                id={titleId}
-                testId={testId && `${testId}-title`}
-            >
-                {title}
-            </HeadingMedium>
-            {subtitle && (
-                <LabelSmall
-                    style={light && styles.subtitle}
-                    testId={testId && `${testId}-subtitle`}
-                >
-                    {subtitle}
-                </LabelSmall>
-            )}
-        </View>
-    );
-}
-
-/**
- * Media query for small screens.
- * TODO(WB-1655): Change this to use the theme instead (inside themedStylesFn).
- * e.g. `[theme.breakpoints.small]: {...}`
- */
-const small = "@media (max-width: 767px)";
-
-const themedStylesFn: ThemedStylesFn<ModalDialogThemeContract> = (theme) => ({
-    header: {
-        boxShadow: `0px 1px 0px ${theme.color.shadow.default}`,
-        display: "flex",
-        flexDirection: "column",
-        minHeight: 66,
-        padding: `${theme.spacing.header.medium}px ${theme.spacing.header.large}px`,
-        position: "relative",
-        width: "100%",
-
-        [small]: {
-            paddingLeft: theme.spacing.header.small,
-            paddingRight: theme.spacing.header.small,
-        },
-    },
-
-    dark: {
-        background: theme.color.bg.inverse,
-        color: theme.color.text.inverse,
-    },
-
-    breadcrumbs: {
-        color: theme.color.text.secondary,
-        marginBottom: theme.spacing.header.xsmall,
-    },
-
-    title: {
-        // Prevent title from overlapping the close button
-        paddingRight: theme.spacing.header.small,
-        [small]: {
-            paddingRight: theme.spacing.header.large,
-        },
-    },
-
-    subtitle: {
-        color: theme.color.text.secondary,
-        marginTop: theme.spacing.header.xsmall,
-    },
-});
-
-ModalHeader.defaultProps = {
-    light: true,
-};

package/src/components/modal-launcher.tsx

@@ -1,297 +0,0 @@
-import * as React from "react";
-import * as ReactDOM from "react-dom";
-import {StyleSheet} from "aphrodite";
-
-import {withActionScheduler} from "@khanacademy/wonder-blocks-timing";
-import type {WithActionSchedulerProps} from "@khanacademy/wonder-blocks-timing";
-
-import FocusTrap from "./focus-trap";
-import ModalBackdrop from "./modal-backdrop";
-import ScrollDisabler from "./scroll-disabler";
-import type {ModalElement} from "../util/types";
-import ModalContext from "./modal-context";
-
-type Props = Readonly<{
-    /**
-     * The modal to render.
-     *
-     * The modal will be rendered inside of a container whose parent is
-     * document.body. This allows us to use ModalLauncher within menus and
-     * other components that clip their content. If the modal needs to close
-     * itself by some other means than tapping the backdrop or the default
-     * close button a render callback can be passed. The closeModal function
-     * provided to this callback can be called to close the modal.
-     *
-     * Note: Don't call `closeModal` while rendering! It should be used to
-     * respond to user intearction, like `onClick`.
-     */
-    modal: ModalElement | ((props: {closeModal: () => void}) => ModalElement);
-    /**
-     * Enables the backdrop to dismiss the modal on click/tap
-     */
-    backdropDismissEnabled?: boolean;
-    /**
-     * The selector for the element that will be focused when the dialog shows.
-     * When not set, the first tabbable element within the dialog will be used.
-     */
-    initialFocusId?: string;
-    /**
-     * The selector for the element that will be focused after the dialog
-     * closes. When not set, the last element focused outside the modal will
-     * be used if it exists.
-     */
-    closedFocusId?: string;
-    /**
-     * Test ID used for e2e testing. It's set on the ModalBackdrop
-     */
-    testId?: string;
-
-    /**
-     * Renders the modal 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 modal
-     * when using this prop.  `onClose` should always be used and `children`
-     * should never be used with this prop.  Not doing so will result in an
-     * error being thrown.
-     */
-    opened?: boolean;
-
-    /**
-     * If the parent needs to be notified when the modal is closed, use this
-     * prop. You probably want to use this instead of `onClose` on the modals
-     * themselves, since this will capture a more complete set of close events.
-     *
-     * Called when the modal needs to notify the parent component that it should
-     * be closed.
-     *
-     * This prop must be used when the component is being used as a controlled
-     * component.
-     */
-    onClose?: () => unknown;
-
-    /**
-     * WARNING: This props should only be used when using the component as a
-     * controlled component.
-     */
-    children?: (arg1: {openModal: () => unknown}) => React.ReactNode;
-}> &
-    WithActionSchedulerProps;
-
-type DefaultProps = Readonly<{
-    backdropDismissEnabled: Props["backdropDismissEnabled"];
-}>;
-
-type State = Readonly<{
-    /** Whether the modal should currently be open. */
-    opened: boolean;
-}>;
-
-/**
- * This component enables you to launch a modal, covering the screen.
- *
- * Children have access to `openModal` function via the function-as-children
- * pattern, so one common use case is for this component to wrap a button:
- *
- * ```js
- * <ModalLauncher modal={<TwoColumnModal ... />}>
- *     {({openModal}) => <button onClick={openModal}>Learn more</button>}
- * </ModalLauncher>
- * ```
- *
- * The actual modal itself is constructed separately, using a layout component
- * like OnePaneDialog and is provided via
- * the `modal` prop.
- */
-class ModalLauncher extends React.Component<Props, State> {
-    /**
-     * The most recent element _outside this component_ that received focus.
-     * Be default, it captures the element that triggered the modal opening
-     */
-    lastElementFocusedOutsideModal: HTMLElement | null | undefined;
-
-    static defaultProps: DefaultProps = {
-        backdropDismissEnabled: true,
-    };
-
-    static getDerivedStateFromProps(
-        props: Props,
-        state: State,
-    ): Partial<State> {
-        if (typeof props.opened === "boolean" && props.children) {
-            // eslint-disable-next-line no-console
-            console.warn("'children' and 'opened' can't be used together");
-        }
-        if (typeof props.opened === "boolean" && !props.onClose) {
-            // eslint-disable-next-line no-console
-            console.warn("'onClose' should be used with 'opened'");
-        }
-        if (typeof props.opened !== "boolean" && !props.children) {
-            // eslint-disable-next-line no-console
-            console.warn("either 'children' or 'opened' must be set");
-        }
-        return {
-            opened:
-                typeof props.opened === "boolean" ? props.opened : state.opened,
-        };
-    }
-
-    state: State = {opened: false};
-
-    componentDidUpdate(prevProps: Props) {
-        // ensures the element is stored only when the modal is opened
-        if (!prevProps.opened && this.props.opened) {
-            this._saveLastElementFocused();
-        }
-    }
-
-    _saveLastElementFocused: () => void = () => {
-        // keep a reference of the element that triggers the modal
-        // @ts-expect-error [FEI-5019] - TS2322 - Type 'Element | null' is not assignable to type 'HTMLElement | null | undefined'.
-        this.lastElementFocusedOutsideModal = document.activeElement;
-    };
-
-    _openModal: () => void = () => {
-        this._saveLastElementFocused();
-        this.setState({opened: true});
-    };
-
-    _returnFocus: () => void = () => {
-        const {closedFocusId, schedule} = this.props;
-        const lastElement = this.lastElementFocusedOutsideModal;
-
-        // Focus on the specified element after closing the modal.
-        if (closedFocusId) {
-            const focusElement = ReactDOM.findDOMNode(
-                document.getElementById(closedFocusId),
-            ) as any;
-
-            if (focusElement) {
-                // Wait for the modal to leave the DOM before trying
-                // to focus on the specified element.
-                schedule.animationFrame(() => {
-                    focusElement.focus();
-                });
-                return;
-            }
-        }
-
-        if (lastElement != null) {
-            // Wait for the modal to leave the DOM before trying to
-            // return focus to the element that triggered the modal.
-            schedule.animationFrame(() => {
-                lastElement.focus();
-            });
-        }
-    };
-
-    handleCloseModal: () => void = () => {
-        this.setState({opened: false}, () => {
-            const {onClose} = this.props;
-
-            onClose?.();
-            this._returnFocus();
-        });
-    };
-
-    _renderModal(): ModalElement {
-        if (typeof this.props.modal === "function") {
-            return this.props.modal({
-                closeModal: this.handleCloseModal,
-            });
-        } else {
-            return this.props.modal;
-        }
-    }
-
-    render(): React.ReactElement | null {
-        const renderedChildren = this.props.children
-            ? this.props.children({
-                  openModal: this._openModal,
-              })
-            : null;
-
-        const {body} = document;
-        if (!body) {
-            return null;
-        }
-
-        return (
-            <ModalContext.Provider value={{closeModal: this.handleCloseModal}}>
-                {renderedChildren}
-                {this.state.opened &&
-                    ReactDOM.createPortal(
-                        /* We need the container View that FocusTrap creates to be at the
-                           correct z-index so that it'll be above the global nav in webapp. */
-                        <FocusTrap style={styles.container}>
-                            <ModalBackdrop
-                                initialFocusId={this.props.initialFocusId}
-                                testId={this.props.testId}
-                                onCloseModal={
-                                    this.props.backdropDismissEnabled
-                                        ? this.handleCloseModal
-                                        : () => {}
-                                }
-                            >
-                                {this._renderModal()}
-                            </ModalBackdrop>
-                        </FocusTrap>,
-                        body,
-                    )}
-                {this.state.opened && (
-                    <ModalLauncherKeypressListener
-                        onClose={this.handleCloseModal}
-                    />
-                )}
-                {this.state.opened && <ScrollDisabler />}
-            </ModalContext.Provider>
-        );
-    }
-}
-
-/** A component that, when mounted, calls `onClose` when Escape is pressed. */
-class ModalLauncherKeypressListener extends React.Component<{
-    onClose: () => unknown;
-}> {
-    componentDidMount() {
-        window.addEventListener("keyup", this._handleKeyup);
-    }
-
-    componentWillUnmount() {
-        window.removeEventListener("keyup", this._handleKeyup);
-    }
-
-    _handleKeyup = (e: KeyboardEvent) => {
-        // 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();
-            this.props.onClose();
-        }
-    };
-
-    render(): React.ReactElement | null {
-        return null;
-    }
-}
-
-const styles = StyleSheet.create({
-    container: {
-        // This z-index is copied from the Khan Academy webapp.
-        //
-        // TODO(mdr): Should we keep this in a constants file somewhere? Or
-        //     not hardcode it at all, and provide it to Wonder Blocks via
-        //     configuration?
-        zIndex: 1080,
-    },
-});
-
-export default withActionScheduler(ModalLauncher);

package/src/components/modal-panel.tsx

@@ -1,188 +0,0 @@
-import * as React from "react";
-import {PropsFor, View} from "@khanacademy/wonder-blocks-core";
-import type {StyleType} from "@khanacademy/wonder-blocks-core";
-
-import {
-    ThemedStylesFn,
-    useScopedTheme,
-    useStyles,
-} from "@khanacademy/wonder-blocks-theming";
-import ModalContent from "./modal-content";
-import ModalHeader from "./modal-header";
-import ModalFooter from "./modal-footer";
-import CloseButton from "./close-button";
-import {
-    ModalDialogThemeContext,
-    ModalDialogThemeContract,
-} from "../themes/themed-modal-dialog";
-
-type Props = {
-    /**
-     * The main contents of the ModalPanel. All other parts of the panel
-     * are positioned around it.
-     */
-    content:
-        | React.ReactElement<PropsFor<typeof ModalContent>>
-        | React.ReactNode;
-    /**
-     * The modal header to show at the top of the panel.
-     */
-    header?: React.ReactElement<PropsFor<typeof ModalHeader>> | React.ReactNode;
-    /**
-     * A footer to show beneath the contents.
-     */
-    footer?: React.ReactElement<PropsFor<typeof ModalFooter>> | React.ReactNode;
-    /**
-     * When true, the close button is shown; otherwise, the close button is not shown.
-     */
-    closeButtonVisible: boolean;
-    /**
-     * Should the contents of the panel become scrollable should they
-     * become too tall?
-     */
-    scrollOverflow: boolean;
-    /**
-     * Whether to display the "light" version of this component instead, for
-     * use when the item is used on a dark background.
-     */
-    light: boolean;
-    /**
-     * Any optional styling to apply to the panel.
-     */
-    style?: StyleType;
-    /**
-     * Called when the close button is clicked.
-     *
-     * If you're using `ModalLauncher`, you should not use this prop!
-     * Instead, to listen for when the modal closes, add an `onClose` handler
-     * to the `ModalLauncher`.  Doing so will throw an error.
-     */
-    onClose?: () => unknown;
-    /**
-     * Test ID used for e2e testing.
-     *
-     * In this case, this `testId` comes from the `testId` prop defined in the
-     * Dialog variant (e.g. OnePaneDialog).
-     */
-    testId?: string;
-};
-
-/**
- * ModalPanel is the content container.
- *
- * **Implementation notes:**
- *
- * If you are creating a custom Dialog, make sure to follow these guidelines:
- * - Make sure to add this component inside the [ModalDialog](/#modaldialog).
- * - If needed, you can also add a [ModalHeader](/#modalheader) using the
- *   `header` prop. Same goes for [ModalFooter](/#modalfooter).
- * - If you need to create e2e tests, make sure to pass a `testId` prop. This
- *   will be passed down to this component using a sufix: e.g.
- *   `some-random-id-ModalPanel`. This scope will be propagated to the
- *   CloseButton element as well: e.g. `some-random-id-CloseButton`.
- *
- * ```js
- * <ModalDialog>
- *      <ModalPanel content={"custom content goes here"} />
- * </ModalDialog>
- * ```
- */
-export default function ModalPanel({
-    closeButtonVisible = true,
-    scrollOverflow = true,
-    light = true,
-    content,
-    footer,
-    header,
-    onClose,
-    style,
-    testId,
-}: Props) {
-    const {theme} = useScopedTheme(ModalDialogThemeContext);
-    const styles = useStyles(themedStylesFn, theme);
-
-    const renderMainContent = React.useCallback((): React.ReactNode => {
-        const mainContent = ModalContent.isComponentOf(content) ? (
-            (content as React.ReactElement<PropsFor<typeof ModalContent>>)
-        ) : (
-            <ModalContent>{content}</ModalContent>
-        );
-
-        if (!mainContent) {
-            return mainContent;
-        }
-
-        return React.cloneElement(mainContent, {
-            // Pass the scrollOverflow and header in to the main content
-            scrollOverflow,
-            // We override the styling of the main content to help position
-            // it if there is a footer or close button being
-            // shown. We have to do this here as the ModalContent doesn't
-            // know about things being positioned around it.
-            style: [!!footer && styles.hasFooter, mainContent.props.style],
-        });
-    }, [content, footer, scrollOverflow, styles.hasFooter]);
-
-    const mainContent = renderMainContent();
-
-    return (
-        <View
-            style={[styles.wrapper, !light && styles.dark, style]}
-            testId={testId && `${testId}-panel`}
-        >
-            {closeButtonVisible && (
-                <CloseButton
-                    light={!light}
-                    onClick={onClose}
-                    style={styles.closeButton}
-                    testId={testId && `${testId}-close`}
-                />
-            )}
-            {header}
-            {mainContent}
-            {!footer || ModalFooter.isComponentOf(footer) ? (
-                footer
-            ) : (
-                <ModalFooter>{footer}</ModalFooter>
-            )}
-        </View>
-    );
-}
-
-ModalPanel.defaultProps = {
-    closeButtonVisible: true,
-    scrollOverflow: true,
-    light: true,
-};
-
-const themedStylesFn: ThemedStylesFn<ModalDialogThemeContract> = (theme) => ({
-    wrapper: {
-        flex: "1 1 auto",
-        position: "relative",
-        display: "flex",
-        flexDirection: "column",
-        background: "white",
-        boxSizing: "border-box",
-        overflow: "hidden",
-        height: "100%",
-        width: "100%",
-    },
-
-    closeButton: {
-        position: "absolute",
-        right: theme.spacing.panel.closeButton,
-        top: theme.spacing.panel.closeButton,
-        // This is to allow the button to be tab-ordered before the modal
-        // content but still be above the header and content.
-        zIndex: 1,
-    },
-
-    dark: {
-        background: theme.color.bg.inverse,
-        color: theme.color.text.inverse,
-    },
-
-    hasFooter: {
-        paddingBottom: theme.spacing.panel.footer,
-    },
-});