@khanacademy/wonder-blocks-modal 2.3.4 → 2.3.6

package/src/components/focus-trap.js

@@ -6,6 +6,13 @@ import {View} from "@khanacademy/wonder-blocks-core";
 
 import type {StyleType} from "@khanacademy/wonder-blocks-core";
 
+/**
+ * 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"])';
+
 /**
  * This component ensures that focus stays within itself. If the user uses Tab
  * at the end of the modal, or Shift-Tab at the start of the modal, then this
@@ -35,35 +42,11 @@ type Props = {|
 |};
 
 export default class FocusTrap extends React.Component<Props> {
-    /** The most recent node _inside this component_ to receive focus. */
-    lastNodeFocusedInModal: ?Node;
-
-    /**
-     * Whether we're currently applying programmatic focus, and should therefore
-     * ignore focus change events.
-     */
-    ignoreFocusChanges: boolean;
-
     /**
      * Tabbing is restricted to descendents of this element.
      */
     modalRoot: ?Node;
 
-    constructor(props: Props) {
-        super(props);
-
-        this.lastNodeFocusedInModal = null;
-        this.ignoreFocusChanges = false;
-    }
-
-    componentDidMount() {
-        window.addEventListener("focus", this.handleGlobalFocus, true);
-    }
-
-    componentWillUnmount() {
-        window.removeEventListener("focus", this.handleGlobalFocus, true);
-    }
-
     getModalRoot: (node: any) => void = (node) => {
         if (!node) {
             // The component is being umounted
@@ -79,98 +62,54 @@ export default class FocusTrap extends React.Component<Props> {
         this.modalRoot = modalRoot;
     };
 
-    /** Try to focus the given node. Return true iff successful. */
+    /**
+     * Try to focus the given node. Return true if successful.
+     */
     tryToFocus(node: Node): ?boolean {
         if (node instanceof HTMLElement) {
-            this.ignoreFocusChanges = true;
             try {
                 node.focus();
             } catch (e) {
                 // ignore error
             }
-            this.ignoreFocusChanges = false;
 
             return document.activeElement === node;
         }
     }
 
     /**
-     * Focus the first focusable descendant of the given node.
+     * Focus the next available focusable element within the modal root.
      *
-     * Return true if we succeed. Or, if the given node has no focusable
-     * descendants, return false.
+     * @param {boolean} isLast Used to determine the next available item. true =
+     * First element within the modal, false = Last element within the modal.
      */
-    focusFirstElementIn(currentParent: Node): boolean {
-        const children = currentParent.childNodes;
-        for (let i = 0; i < children.length; i++) {
-            const child = children[i];
-            if (this.tryToFocus(child) || this.focusFirstElementIn(child)) {
-                return true;
-            }
-        }
-        return false;
+    focusElementIn(isLast: boolean) {
+        const modalRootAsHtmlEl = ((this.modalRoot: any): HTMLElement);
+        // Get the list of available focusable elements within the modal.
+        const focusableNodes = Array.from(
+            modalRootAsHtmlEl.querySelectorAll(FOCUSABLE_ELEMENTS),
+        );
+
+        const nodeIndex = !isLast ? focusableNodes.length - 1 : 0;
+
+        const focusableNode = focusableNodes[nodeIndex];
+        this.tryToFocus(focusableNode);
     }
 
     /**
-     * Focus the last focusable descendant of the given node.
-     *
-     * Return true if we succeed. Or, if the given node has no focusable
-     * descendants, return false.
+     * Triggered when the focus is set to the first sentinel. This way, the
+     * focus will be redirected to the last element inside the modal dialog.
      */
-    focusLastElementIn(currentParent: Node): boolean {
-        const children = currentParent.childNodes;
-        for (let i = children.length - 1; i >= 0; i--) {
-            const child = children[i];
-            if (this.tryToFocus(child) || this.focusLastElementIn(child)) {
-                return true;
-            }
-        }
-        return false;
-    }
-
-    /** This method is called when any node on the page is focused. */
-    handleGlobalFocus: (e: FocusEvent) => void = (e) => {
-        // If we're busy applying our own programmatic focus, we ignore focus
-        // changes, to avoid an infinite loop.
-        if (this.ignoreFocusChanges) {
-            return;
-        }
-
-        const target = e.target;
-        if (!(target instanceof Node)) {
-            // Sometimes focus events trigger on the document itself. Ignore!
-            return;
-        }
-
-        const modalRoot = this.modalRoot;
-        if (!modalRoot) {
-            return;
-        }
-
-        if (modalRoot.contains(target)) {
-            // If the newly focused node is inside the modal, we just keep track
-            // of that.
-            this.lastNodeFocusedInModal = target;
-        } else {
-            // If the newly focused node is outside the modal, we try refocusing
-            // the first focusable node of the modal. (This could be the user
-            // pressing Tab on the last node of the modal, or focus escaping in
-            // some other way.)
-            this.focusFirstElementIn(modalRoot);
-
-            // But, if it turns out that the first focusable node of the modal
-            // was what we were previously focusing, then this is probably the
-            // user pressing Shift-Tab on the first node, wanting to go to the
-            // end. So, we instead try focusing the last focusable node of the
-            // modal.
-            if (document.activeElement === this.lastNodeFocusedInModal) {
-                this.focusLastElementIn(modalRoot);
-            }
+    handleFocusMoveToLast: () => void = () => {
+        this.focusElementIn(false);
+    };
 
-            // Focus should now be inside the modal, so record the newly-focused
-            // node as the last node focused in the modal.
-            this.lastNodeFocusedInModal = document.activeElement;
-        }
+    /**
+     * Triggered when the focus is set to the last sentinel. This way, the focus
+     * will be redirected to the first element inside the modal dialog.
+     */
+    handleFocusMoveToFirst: () => void = () => {
+        this.focusElementIn(true);
     };
 
     render(): React.Node {
@@ -190,11 +129,21 @@ export default class FocusTrap extends React.Component<Props> {
                  * We set the sentinels to be position: fixed to make sure
                  * they're always in view, this prevents page scrolling when
                  * tabbing. */}
-                <div tabIndex="0" style={{position: "fixed"}} />
+                <div
+                    tabIndex="0"
+                    className="modal-focus-trap-first"
+                    onFocus={this.handleFocusMoveToLast}
+                    style={{position: "fixed"}}
+                />
                 <View style={style} ref={this.getModalRoot}>
                     {this.props.children}
                 </View>
-                <div tabIndex="0" style={{position: "fixed"}} />
+                <div
+                    tabIndex="0"
+                    className="modal-focus-trap-last"
+                    onFocus={this.handleFocusMoveToFirst}
+                    style={{position: "fixed"}}
+                />
             </React.Fragment>
         );
     }

package/src/components/modal-footer.js

@@ -17,6 +17,14 @@ type Props = {|
  * 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 `footer` prop.
  * - The footer is completely flexible. Meaning the developer needs to add its own custom layout to match design specs.
+ *
+ * **Usage**
+ *
+ * ```js
+ * <ModalFooter>
+ *     <Button onClick={() => {}}>Submit</Button>
+ * </ModalFooter>
+ * ```
  */
 export default class ModalFooter extends React.Component<Props> {
     static isClassOf(instance: any): boolean {

package/src/components/one-pane-dialog.js

@@ -114,7 +114,32 @@ type DefaultProps = {|
  * This is the standard layout for most straightforward modal experiences.
  *
  * The ModalHeader is required, but the ModalFooter is optional.
- * The content of the dialog itself is fully customizable, but the left/right/top/bottom padding is fixed.
+ * The content of the dialog itself is fully customizable, but the
+ * left/right/top/bottom padding is fixed.
+ *
+ * ### Usage
+ *
+ * ```jsx
+ * import {OnePaneDialog} from "@khanacademy/wonder-blocks-modal";
+ * import {Body} from "@khanacademy/wonder-blocks-typography";
+ *
+ * <OnePaneDialog
+ *     title="Some title"
+ *     content={
+ *         <Body>
+ *             {`Lorem ipsum dolor sit amet, consectetur adipiscing
+ *             elit, sed do eiusmod tempor incididunt ut labore et
+ *             dolore magna aliqua. Ut enim ad minim veniam,
+ *             quis nostrud exercitation ullamco laboris nisi ut
+ *             aliquip ex ea commodo consequat. Duis aute irure
+ *             dolor in reprehenderit in voluptate velit esse
+ *             cillum dolore eu fugiat nulla pariatur. Excepteur
+ *             sint occaecat cupidatat non proident, sunt in culpa
+ *             qui officia deserunt mollit anim id est.`}
+ *         </Body>
+ *     }
+ * />
+ * ```
  */
 export default class OnePaneDialog extends React.Component<Props> {
     static defaultProps: DefaultProps = {

package/src/components/one-pane-dialog.stories.js

@@ -1,248 +0,0 @@
-/* eslint-disable no-alert */
-// @flow
-import * as React from "react";
-import {StyleSheet} from "aphrodite";
-
-import {View} from "@khanacademy/wonder-blocks-core";
-import {Body} from "@khanacademy/wonder-blocks-typography";
-import Button from "@khanacademy/wonder-blocks-button";
-import {ActionMenu, ActionItem} from "@khanacademy/wonder-blocks-dropdown";
-
-import type {StoryComponentType} from "@storybook/react";
-import OnePaneDialog from "./one-pane-dialog.js";
-import ModalLauncher from "./modal-launcher.js";
-
-import type {ModalElement} from "../util/types.js";
-
-const customViewports = {
-    phone: {
-        name: "phone",
-        styles: {
-            width: "320px",
-            height: "568px",
-        },
-    },
-    tablet: {
-        name: "tablet",
-        styles: {
-            width: "640px",
-            height: "960px",
-        },
-    },
-    desktop: {
-        name: "desktop",
-        styles: {
-            width: "1024px",
-            height: "768px",
-        },
-    },
-};
-
-export default {
-    title: "Floating/Modal/OnePaneDialog",
-    parameters: {
-        viewport: {
-            viewports: customViewports,
-            defaultViewport: "desktop",
-        },
-        chromatic: {
-            viewports: [320, 640, 1024],
-        },
-    },
-};
-
-export const Simple: StoryComponentType = () => {
-    const modal = (
-        <OnePaneDialog
-            testId="one-pane-dialog-above"
-            title="Hello, world!"
-            content={
-                <View>
-                    <Body>
-                        {
-                            "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est."
-                        }
-                    </Body>
-                </View>
-            }
-            closeButtonVisible={true}
-        />
-    );
-
-    return (
-        <ModalLauncher
-            modal={modal}
-            testId="modal-launcher-default-example"
-            opened={true}
-            onClose={() => alert("This would close the modal.")}
-        />
-    );
-};
-
-const styles = StyleSheet.create({
-    above: {
-        background: "url(./modal-above.png)",
-        width: 874,
-        height: 551,
-        position: "absolute",
-        top: 40,
-        left: -140,
-    },
-
-    below: {
-        background: "url(./modal-below.png)",
-        width: 868,
-        height: 521,
-        position: "absolute",
-        top: -100,
-        left: -300,
-    },
-});
-
-export const KitchenSink: StoryComponentType = () => {
-    const modal = (
-        <OnePaneDialog
-            title="Single-line title"
-            subtitle="Subtitle that provides additional context to the title"
-            testId="one-pane-dialog-above"
-            content={
-                <View>
-                    <Body>
-                        {
-                            "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est."
-                        }
-                    </Body>
-                    <br />
-                    <Body>
-                        {
-                            "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est."
-                        }
-                    </Body>
-                    <br />
-                    <Body>
-                        {
-                            "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est."
-                        }
-                    </Body>
-                </View>
-            }
-            footer={<Button onClick={() => {}}>Button (no-op)</Button>}
-            closeButtonVisible={true}
-            above={<View style={styles.above} />}
-            below={<View style={styles.below} />}
-        />
-    );
-
-    return (
-        <ModalLauncher
-            modal={modal}
-            testId="modal-launcher-default-example"
-            opened={true}
-            onClose={() => alert("This would close the modal.")}
-        />
-    );
-};
-
-export const WithOpener: StoryComponentType = () => {
-    type MyModalProps = {|
-        closeModal: () => void,
-    |};
-
-    const MyModal = ({closeModal}: MyModalProps): ModalElement => (
-        <OnePaneDialog
-            title="Single-line title"
-            subtitle="Subtitle that provides additional context to the title"
-            testId="one-pane-dialog-above"
-            content={
-                <View>
-                    <Body>
-                        {
-                            "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est."
-                        }
-                    </Body>
-                    <br />
-                    <Body>
-                        {
-                            "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est."
-                        }
-                    </Body>
-                    <br />
-                    <Body>
-                        {
-                            "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est."
-                        }
-                    </Body>
-                </View>
-            }
-            footer={<Button onClick={() => {}}>Button (no-op)</Button>}
-            closeButtonVisible={true}
-            above={<View style={styles.above} />}
-            below={<View style={styles.below} />}
-        />
-    );
-
-    return (
-        <ModalLauncher
-            modal={MyModal}
-            testId="modal-launcher-default-example"
-            onClose={() => alert("This would close the modal.")}
-        >
-            {({openModal}) => <Button onClick={openModal}>Click me</Button>}
-        </ModalLauncher>
-    );
-};
-
-WithOpener.parameters = {
-    viewport: {
-        defaultViewport: null,
-    },
-    chromatic: {
-        // Don't take screenshots of this story since it would only show a button.
-        disableSnapshot: true,
-    },
-};
-
-export const WithClosedFocusId: StoryComponentType = () => {
-    const [opened, setOpened] = React.useState(false);
-
-    const handleOpen = () => {
-        setOpened(true);
-    };
-
-    const handleClose = () => {
-        setOpened(false);
-    };
-
-    return (
-        <View style={{gap: 20}}>
-            <Button>Top of page (should not receive focus)</Button>
-            <Button id="button-to-focus-on">Focus here after close</Button>
-            <ActionMenu menuText="actions">
-                <ActionItem label="Open modal" onClick={() => handleOpen()} />
-            </ActionMenu>
-            <ModalLauncher
-                onClose={() => handleClose()}
-                opened={opened}
-                closedFocusId="button-to-focus-on"
-                modal={({closeModal}) => (
-                    <OnePaneDialog
-                        title="Triggered from action menu"
-                        content={<View>Hello World</View>}
-                        footer={
-                            <Button onClick={closeModal}>Close Modal</Button>
-                        }
-                    />
-                )}
-            />
-        </View>
-    );
-};
-
-WithClosedFocusId.parameters = {
-    chromatic: {
-        // Don't take screenshots of this story since the case we want
-        // to test doesn't appear on first render - it occurs after
-        // we complete a series of steps.
-        disableSnapshot: true,
-    },
-};