@khanacademy/math-input 0.4.1 → 0.5.2

package/src/components/gesture-manager.js

@@ -0,0 +1,226 @@
+/**
+ * A high-level manager for our gesture system. In particular, this class
+ * connects our various bits of logic for managing gestures and interactions,
+ * and links them together.
+ */
+
+import GestureStateMachine from "./gesture-state-machine.js";
+import NodeManager from "./node-manager.js";
+import PopoverStateMachine from "./popover-state-machine.js";
+
+const coordsForEvent = (evt) => {
+    return [evt.changedTouches[0].clientX, evt.changedTouches[0].clientY];
+};
+
+class GestureManager {
+    constructor(options, handlers, disabledSwipeKeys, multiPressableKeys) {
+        const {swipeEnabled} = options;
+
+        this.swipeEnabled = swipeEnabled;
+
+        // Events aren't tracked until event tracking is enabled.
+        this.trackEvents = false;
+
+        this.nodeManager = new NodeManager();
+        this.popoverStateMachine = new PopoverStateMachine({
+            onActiveNodesChanged: (activeNodes) => {
+                const {popover, ...rest} = activeNodes;
+                handlers.onActiveNodesChanged({
+                    popover: popover && {
+                        parentId: popover.parentId,
+                        bounds: this.nodeManager.layoutPropsForId(
+                            popover.parentId,
+                        ).initialBounds,
+                        childKeyIds: popover.childIds,
+                    },
+                    ...rest,
+                });
+            },
+            /**
+             * `onClick` takes two arguments:
+             *
+             * @param {string} keyId - the identifier key that should initiate
+             *                         a click
+             * @param {string} domNodeId - the identifier of the DOM node on
+             *                             which the click should be considered
+             *                             to have occurred
+             * @param {bool} inPopover - whether the key was contained within a
+             *                           popover
+             *
+             * These two parameters will often be equivalent. They will differ,
+             * though, when a popover button is itself clicked, in which case
+             * we need to mimic the effects of clicking on its 'primary' child
+             * key, but animate the click on the popover button.
+             */
+            onClick: (keyId, domNodeId, inPopover) => {
+                handlers.onClick(
+                    keyId,
+                    this.nodeManager.layoutPropsForId(domNodeId),
+                    inPopover,
+                );
+            },
+        });
+        this.gestureStateMachine = new GestureStateMachine(
+            {
+                onFocus: (id) => {
+                    this.popoverStateMachine.onFocus(id);
+                },
+                onLongPress: (id) => {
+                    this.popoverStateMachine.onLongPress(id);
+                },
+                onTouchEnd: (id) => {
+                    this.popoverStateMachine.onTouchEnd(id);
+                },
+                onBlur: () => {
+                    this.popoverStateMachine.onBlur();
+                },
+                onSwipeChange: handlers.onSwipeChange,
+                onSwipeEnd: handlers.onSwipeEnd,
+                onTrigger: (id) => {
+                    this.popoverStateMachine.onTrigger(id);
+                },
+            },
+            {},
+            disabledSwipeKeys,
+            multiPressableKeys,
+        );
+    }
+
+    /**
+     * Handle a touch-start event that originated in a node registered with the
+     * gesture system.
+     *
+     * @param {TouchEvent} evt - the raw touch event from the browser
+     * @param {string} id - the identifier of the DOM node in which the touch
+     *                      occurred
+     */
+    onTouchStart(evt, id) {
+        if (!this.trackEvents) {
+            return;
+        }
+
+        const [x] = coordsForEvent(evt);
+
+        // TODO(charlie): It doesn't seem to be guaranteed that every touch
+        // event on `changedTouches` originates from the node through which this
+        // touch event was sent. In that case, we'd be inappropriately reporting
+        // the starting node ID.
+        for (let i = 0; i < evt.changedTouches.length; i++) {
+            this.gestureStateMachine.onTouchStart(
+                () => id,
+                evt.changedTouches[i].identifier,
+                x,
+            );
+        }
+
+        // If an event started in a view that we're managing, we'll handle it
+        // all the way through.
+        evt.preventDefault();
+    }
+
+    /**
+     * Handle a touch-move event that originated in a node registered with the
+     * gesture system.
+     *
+     * @param {TouchEvent} evt - the raw touch event from the browser
+     */
+    onTouchMove(evt) {
+        if (!this.trackEvents) {
+            return;
+        }
+
+        const swipeLocked = this.popoverStateMachine.isPopoverVisible();
+        const swipeEnabled = this.swipeEnabled && !swipeLocked;
+        const [x, y] = coordsForEvent(evt);
+        for (let i = 0; i < evt.changedTouches.length; i++) {
+            this.gestureStateMachine.onTouchMove(
+                () => this.nodeManager.idForCoords(x, y),
+                evt.changedTouches[i].identifier,
+                x,
+                swipeEnabled,
+            );
+        }
+    }
+
+    /**
+     * Handle a touch-end event that originated in a node registered with the
+     * gesture system.
+     *
+     * @param {TouchEvent} evt - the raw touch event from the browser
+     */
+    onTouchEnd(evt) {
+        if (!this.trackEvents) {
+            return;
+        }
+
+        const [x, y] = coordsForEvent(evt);
+        for (let i = 0; i < evt.changedTouches.length; i++) {
+            this.gestureStateMachine.onTouchEnd(
+                () => this.nodeManager.idForCoords(x, y),
+                evt.changedTouches[i].identifier,
+                x,
+            );
+        }
+    }
+
+    /**
+     * Handle a touch-cancel event that originated in a node registered with the
+     * gesture system.
+     *
+     * @param {TouchEvent} evt - the raw touch event from the browser
+     */
+    onTouchCancel(evt) {
+        if (!this.trackEvents) {
+            return;
+        }
+
+        for (let i = 0; i < evt.changedTouches.length; i++) {
+            this.gestureStateMachine.onTouchCancel(
+                evt.changedTouches[i].identifier,
+            );
+        }
+    }
+
+    /**
+     * Register a DOM node with a given identifier.
+     *
+     * @param {string} id - the identifier of the given node
+     * @param {node} domNode - the DOM node linked to the identifier
+     * @param {string[]} childIds - the identifiers of any DOM nodes that
+     *                              should be considered children of this node,
+     *                              in that they should take priority when
+     *                              intercepting touch events
+     * @param {object} borders - an opaque object describing the node's borders
+     */
+    registerDOMNode(id, domNode, childIds, borders) {
+        this.nodeManager.registerDOMNode(id, domNode, childIds, borders);
+        this.popoverStateMachine.registerPopover(id, childIds);
+    }
+
+    /**
+     * Unregister the DOM node with the given identifier.
+     *
+     * @param {string} id - the identifier of the node to unregister
+     */
+    unregisterDOMNode(id) {
+        this.nodeManager.unregisterDOMNode(id);
+        this.popoverStateMachine.unregisterPopover(id);
+    }
+
+    /**
+     * Enable event tracking for the gesture manager.
+     */
+    enableEventTracking() {
+        this.trackEvents = true;
+    }
+
+    /**
+     * Disable event tracking for the gesture manager. When called, the gesture
+     * manager will drop any events received by managed nodes.
+     */
+    disableEventTracking() {
+        this.trackEvents = false;
+    }
+}
+
+export default GestureManager;

package/src/components/gesture-state-machine.js

@@ -0,0 +1,283 @@
+/**
+ * The state machine that backs our gesture system. In particular, this state
+ * machine manages the interplay between focuses, touch ups, and swiping.
+ * It is entirely ignorant of the existence of popovers and the positions of
+ * DOM nodes, operating solely on IDs. The state machine does accommodate for
+ * multi-touch interactions, tracking gesture state on a per-touch basis.
+ */
+
+const defaults = {
+    longPressWaitTimeMs: 50,
+    swipeThresholdPx: 20,
+    holdIntervalMs: 250,
+};
+
+class GestureStateMachine {
+    constructor(handlers, options, swipeDisabledNodeIds, multiPressableKeys) {
+        this.handlers = handlers;
+        this.options = {
+            ...defaults,
+            ...options,
+        };
+        this.swipeDisabledNodeIds = swipeDisabledNodeIds || [];
+        this.multiPressableKeys = multiPressableKeys || [];
+
+        // TODO(charlie): Flow-type this file. It's not great that we're now
+        // passing around these opaque state objects.
+        this.touchState = {};
+        this.swipeState = null;
+    }
+
+    _maybeCancelLongPressForTouch(touchId) {
+        const {longPressTimeoutId} = this.touchState[touchId];
+        if (longPressTimeoutId) {
+            clearTimeout(longPressTimeoutId);
+            this.touchState[touchId] = {
+                ...this.touchState[touchId],
+                longPressTimeoutId: null,
+            };
+        }
+    }
+
+    _maybeCancelPressAndHoldForTouch(touchId) {
+        const {pressAndHoldIntervalId} = this.touchState[touchId];
+        if (pressAndHoldIntervalId) {
+            // If there was an interval set to detect holds, clear it out.
+            clearInterval(pressAndHoldIntervalId);
+            this.touchState[touchId] = {
+                ...this.touchState[touchId],
+                pressAndHoldIntervalId: null,
+            };
+        }
+    }
+
+    _cleanupTouchEvent(touchId) {
+        this._maybeCancelLongPressForTouch(touchId);
+        this._maybeCancelPressAndHoldForTouch(touchId);
+        delete this.touchState[touchId];
+    }
+
+    /**
+     * Handle a focus event on the node with the given identifier, which may be
+     * `null` to indicate that the user has dragged their finger off of any
+     * registered nodes, but is still in the middle of a gesture.
+     *
+     * @param {string|null} id - the identifier of the newly focused node, or
+     *                           `null` if no node is focused
+     * @param {number} touchId - a unique identifier associated with the touch
+     */
+    _onFocus(id, touchId) {
+        // If we're in the middle of a long-press, cancel it.
+        this._maybeCancelLongPressForTouch(touchId);
+
+        // Reset any existing hold-detecting interval.
+        this._maybeCancelPressAndHoldForTouch(touchId);
+
+        // Set the focused node ID and handle the focus event.
+        // Note: we can call `onFocus` with `null` IDs. The semantics of an
+        // `onFocus` with a `null` ID differs from that of `onBlur`. The former
+        // indicates that a gesture that can focus future nodes is still in
+        // progress, but that no node is currently focused. The latter
+        // indicates that the gesture has ended and nothing will be focused.
+        this.touchState[touchId] = {
+            ...this.touchState[touchId],
+            activeNodeId: id,
+        };
+        this.handlers.onFocus(id);
+
+        if (id) {
+            // Handle logic for repeating button presses.
+            if (this.multiPressableKeys.includes(id)) {
+                // Start by triggering a click, iOS style.
+                this.handlers.onTrigger(id);
+
+                // Set up a new hold detector for the current button.
+                this.touchState[touchId] = {
+                    ...this.touchState[touchId],
+                    pressAndHoldIntervalId: setInterval(() => {
+                        // On every cycle, trigger the click handler.
+                        this.handlers.onTrigger(id);
+                    }, this.options.holdIntervalMs),
+                };
+            } else {
+                // Set up a new hold detector for the current button.
+                this.touchState[touchId] = {
+                    ...this.touchState[touchId],
+                    longPressTimeoutId: setTimeout(() => {
+                        this.handlers.onLongPress(id);
+                        this.touchState[touchId] = {
+                            ...this.touchState[touchId],
+                            longPressTimeoutId: null,
+                        };
+                    }, this.options.longPressWaitTimeMs),
+                };
+            }
+        }
+    }
+
+    /**
+     * Clear out all active gesture information.
+     */
+    _onSwipeStart() {
+        for (const activeTouchId of Object.keys(this.touchState)) {
+            this._maybeCancelLongPressForTouch(activeTouchId);
+            this._maybeCancelPressAndHoldForTouch(activeTouchId);
+        }
+        this.touchState = {};
+        this.handlers.onBlur();
+    }
+
+    /**
+     * A function that returns the identifier of the node over which the touch
+     * event occurred. This is provided as a piece of lazy computation, as
+     * computing the DOM node for a given point is expensive, and the state
+     * machine won't always need that information. For example, if the user is
+     * swiping, then `onTouchMove` needs to be performant and doesn't care about
+     * the node over which the touch occurred.
+     *
+     * @typedef idComputation
+     * @returns {DOMNode} - the identifier of the node over which the touch
+     *                      occurred
+     */
+
+    /**
+     * Handle a touch-start event on the node with the given identifer.
+     *
+     * @param {idComputation} getId - a function that returns identifier of the
+     *                                node over which the start event occurred
+     * @param {number} touchId - a unique identifier associated with the touch
+     */
+    onTouchStart(getId, touchId, pageX) {
+        // Ignore any touch events that start mid-swipe.
+        if (this.swipeState) {
+            return;
+        }
+
+        if (this.touchState[touchId]) {
+            // It turns out we can get multiple touch starts with no
+            // intervening move, end, or cancel events in Android WebViews.
+            // TODO(benkomalo): it's not entirely clear why this happens, but
+            // it seems to happen with the backspace button. It may be related
+            // to FastClick (https://github.com/ftlabs/fastclick/issues/71)
+            // though I haven't verified, and it's probably good to be robust
+            // here anyways.
+            return;
+        }
+
+        const startingNodeId = getId();
+        this.touchState[touchId] = {
+            swipeLocked: this.swipeDisabledNodeIds.includes(startingNodeId),
+            startX: pageX,
+        };
+
+        this._onFocus(startingNodeId, touchId);
+    }
+
+    /**
+     * Handle a touch-move event on the node with the given identifer.
+     *
+     * @param {idComputation} getId - a function that returns identifier of the
+     *                                node over which the move event occurred
+     * @param {number} touchId - a unique identifier associated with the touch
+     * @param {number} pageX - the x coordinate of the touch
+     * @param {boolean} swipeEnabled - whether the system should allow for
+     *                                 transitions into a swiping state
+     */
+    onTouchMove(getId, touchId, pageX, swipeEnabled) {
+        if (this.swipeState) {
+            // Only respect the finger that started a swipe. Any other lingering
+            // gestures are ignored.
+            if (this.swipeState.touchId === touchId) {
+                this.handlers.onSwipeChange(pageX - this.swipeState.startX);
+            }
+        } else if (this.touchState[touchId]) {
+            // It could be touch events started outside the keypad and
+            // moved into it; ignore them.
+            const {activeNodeId, startX, swipeLocked} =
+                this.touchState[touchId];
+
+            const dx = pageX - startX;
+            const shouldBeginSwiping =
+                swipeEnabled &&
+                !swipeLocked &&
+                Math.abs(dx) > this.options.swipeThresholdPx;
+
+            if (shouldBeginSwiping) {
+                this._onSwipeStart();
+
+                // Trigger the swipe.
+                this.swipeState = {
+                    touchId,
+                    startX,
+                };
+                this.handlers.onSwipeChange(pageX - this.swipeState.startX);
+            } else {
+                const id = getId();
+                if (id !== activeNodeId) {
+                    this._onFocus(id, touchId);
+                }
+            }
+        }
+    }
+
+    /**
+     * Handle a touch-end event on the node with the given identifer.
+     *
+     * @param {idComputation} getId - a function that returns identifier of the
+     *                                node over which the end event occurred
+     * @param {number} touchId - a unique identifier associated with the touch
+     * @param {number} pageX - the x coordinate of the touch
+     */
+    onTouchEnd(getId, touchId, pageX) {
+        if (this.swipeState) {
+            // Only respect the finger that started a swipe. Any other lingering
+            // gestures are ignored.
+            if (this.swipeState.touchId === touchId) {
+                this.handlers.onSwipeEnd(pageX - this.swipeState.startX);
+                this.swipeState = null;
+            }
+        } else if (this.touchState[touchId]) {
+            // It could be touch events started outside the keypad and
+            // moved into it; ignore them.
+            const {activeNodeId, pressAndHoldIntervalId} =
+                this.touchState[touchId];
+
+            this._cleanupTouchEvent(touchId);
+
+            const didPressAndHold = !!pressAndHoldIntervalId;
+            if (didPressAndHold) {
+                // We don't trigger a touch end if there was a press and hold,
+                // because the key has been triggered at least once and calling
+                // the onTouchEnd handler would add an extra trigger.
+                this.handlers.onBlur();
+            } else {
+                // Trigger a touch-end. There's no need to notify clients of a
+                // blur as clients are responsible for handling any cleanup in
+                // their touch-end handlers.
+                this.handlers.onTouchEnd(activeNodeId);
+            }
+        }
+    }
+
+    /**
+     * Handle a touch-cancel event.
+     */
+    onTouchCancel(touchId) {
+        // If a touch is cancelled and we're swiping, end the swipe with no
+        // displacement.
+        if (this.swipeState) {
+            if (this.swipeState.touchId === touchId) {
+                this.handlers.onSwipeEnd(0);
+                this.swipeState = null;
+            }
+        } else if (this.touchState[touchId]) {
+            // Otherwise, trigger a full blur. We don't want to trigger a
+            // touch-up, since the cancellation means that the user probably
+            // didn't release over a key intentionally.
+            this._cleanupTouchEvent(touchId);
+            this.handlers.onBlur();
+        }
+    }
+}
+
+export default GestureStateMachine;

package/src/components/icon.js

@@ -0,0 +1,74 @@
+/**
+ * A component that renders an icon for a symbol with the given name.
+ */
+
+import {StyleSheet} from "aphrodite";
+import PropTypes from "prop-types";
+import * as React from "react";
+
+import {IconTypes} from "../consts.js";
+
+import {offBlack} from "./common-style.js";
+import MathIcon from "./math-icon.js";
+import {iconPropType} from "./prop-types.js";
+import SvgIcon from "./svg-icon.js";
+import TextIcon from "./text-icon.js";
+
+const focusedColor = "#FFF";
+const unfocusedColor = offBlack;
+
+class Icon extends React.PureComponent {
+    static propTypes = {
+        focused: PropTypes.bool,
+        icon: iconPropType.isRequired,
+        // An Aphrodite style object, or an array of Aphrodite style objects.
+        // Note that custom styles will only be applied to text and math icons
+        // (and not SVG icons).
+        style: PropTypes.any,
+    };
+
+    render() {
+        const {focused, icon, style} = this.props;
+
+        const styleWithFocus = [
+            focused ? styles.focused : styles.unfocused,
+            ...(Array.isArray(style) ? style : [style]),
+        ];
+
+        switch (icon.type) {
+            case IconTypes.MATH:
+                return <MathIcon math={icon.data} style={styleWithFocus} />;
+
+            case IconTypes.SVG:
+                // TODO(charlie): Support passing style objects to `SvgIcon`.
+                // This will require migrating the individual icons to use
+                // `currentColor` and accept a `className` prop, rather than
+                // relying on an explicit color prop.
+                return (
+                    <SvgIcon
+                        name={icon.data}
+                        color={focused ? focusedColor : unfocusedColor}
+                    />
+                );
+
+            case IconTypes.TEXT:
+                return (
+                    <TextIcon character={icon.data} style={styleWithFocus} />
+                );
+        }
+
+        throw new Error("No icon or symbol provided");
+    }
+}
+
+const styles = StyleSheet.create({
+    unfocused: {
+        color: unfocusedColor,
+    },
+
+    focused: {
+        color: focusedColor,
+    },
+});
+
+export default Icon;

package/src/components/iconography/arrow.js

@@ -0,0 +1,22 @@
+/**
+ * An arrow icon, used by the other navigational keys.
+ */
+import * as React from "react";
+
+const Arrow = (props) => {
+    return (
+        <g fill="none" fillRule="evenodd" {...props}>
+            <path fill="none" d="M0 0h48v48H0z" />
+            <path fill="none" d="M12 12h24v24H12z" />
+            <path
+                stroke="#888D93"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                d="M22 18l-6 6 6 6M16 24h16"
+            />
+        </g>
+    );
+};
+
+export default Arrow;

package/src/components/iconography/backspace.js

@@ -0,0 +1,29 @@
+/**
+ * An autogenerated component that renders the BACKSPACE iconograpy in SVG.
+ *
+ * Generated with: https://gist.github.com/crm416/3c7abc88e520eaed72347af240b32590.
+ */
+import * as React from "react";
+
+const Backspace = () => {
+    return (
+        <svg width="48" height="48" viewBox="0 0 48 48">
+            <g fill="none" fillRule="evenodd">
+                <path fill="none" d="M0 0h48v48H0z" />
+                <path
+                    d="M13 24l6 6h14V18H19l-6 6zm-1.414-1.414l6-6A2 2 0 0 1 19 16h14a2 2 0 0 1 2 2v12a2 2 0 0 1-2 2H19a2 2 0 0 1-1.414-.586l-6-6a2 2 0 0 1 0-2.828z"
+                    fill="#888D93"
+                />
+                <path
+                    d="M23 21l6 6M29 21l-6 6"
+                    stroke="#888D93"
+                    strokeWidth="2"
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                />
+            </g>
+        </svg>
+    );
+};
+
+export default Backspace;

package/src/components/iconography/cdot.js

@@ -0,0 +1,29 @@
+/**
+ * An autogenerated component that renders the CDOT iconograpy in SVG.
+ *
+ * Generated with: https://gist.github.com/crm416/3c7abc88e520eaed72347af240b32590.
+ */
+import PropTypes from "prop-types";
+import * as React from "react";
+
+class Cdot extends React.Component {
+    static propTypes = {
+        color: PropTypes.string.isRequired,
+    };
+
+    render() {
+        return (
+            <svg width="48" height="48" viewBox="0 0 48 48">
+                <g fill="none" fillRule="evenodd">
+                    <path fill="none" d="M0 0h48v48H0z" />
+                    <g transform="translate(12 12)">
+                        <path fill="none" d="M0 0h24v24H0z" />
+                        <circle fill={this.props.color} cx="12" cy="12" r="3" />
+                    </g>
+                </g>
+            </svg>
+        );
+    }
+}
+
+export default Cdot;

package/src/components/iconography/cos.js

@@ -0,0 +1,30 @@
+/**
+ * An autogenerated component that renders the COS iconograpy in SVG.
+ *
+ * Generated with: https://gist.github.com/crm416/3c7abc88e520eaed72347af240b32590.
+ */
+import PropTypes from "prop-types";
+import * as React from "react";
+
+class Cos extends React.Component {
+    static propTypes = {
+        color: PropTypes.string.isRequired,
+    };
+
+    render() {
+        return (
+            <svg width="48" height="48" viewBox="0 0 48 48">
+                <g fill="none" fillRule="evenodd">
+                    <path fill="none" d="M0 0h48v48H0z" />
+                    <path fill="none" d="M13 12h24v24H13z" />
+                    <path
+                        d="M18.182 29.168c1.386 0 2.226-.602 2.674-1.232l-1.162-1.078a1.707 1.707 0 0 1-1.428.728c-1.078 0-1.834-.798-1.834-1.974s.756-1.96 1.834-1.96c.616 0 1.106.252 1.428.728l1.162-1.092c-.448-.616-1.288-1.218-2.674-1.218-2.086 0-3.584 1.47-3.584 3.542 0 2.086 1.498 3.556 3.584 3.556zm6.972 0c2.24 0 3.584-1.624 3.584-3.556 0-1.918-1.344-3.542-3.584-3.542-2.226 0-3.57 1.624-3.57 3.542 0 1.932 1.344 3.556 3.57 3.556zm0-1.582c-1.106 0-1.722-.91-1.722-1.974 0-1.05.616-1.96 1.722-1.96 1.106 0 1.736.91 1.736 1.96 0 1.064-.63 1.974-1.736 1.974zm7.336 1.582c1.876 0 2.926-.938 2.926-2.17 0-2.73-4.004-1.89-4.004-2.898 0-.378.42-.672 1.064-.672.826 0 1.596.35 2.002.784l.714-1.218c-.672-.532-1.582-.924-2.73-.924-1.778 0-2.772.994-2.772 2.128 0 2.66 4.018 1.75 4.018 2.87 0 .42-.364.728-1.134.728-.84 0-1.848-.462-2.338-.924l-.77 1.246c.714.658 1.848 1.05 3.024 1.05z"
+                        fill={this.props.color}
+                    />
+                </g>
+            </svg>
+        );
+    }
+}
+
+export default Cos;