@khanacademy/wonder-blocks-tooltip 1.3.0

package/src/util/__tests__/ref-tracker.test.js

@@ -0,0 +1,153 @@
+// @flow
+import * as React from "react";
+import * as ReactDOM from "react-dom";
+import {mount} from "enzyme";
+
+import {View} from "@khanacademy/wonder-blocks-core";
+
+import RefTracker from "../ref-tracker.js";
+
+type CallbackFn = (?HTMLElement) => void;
+
+describe("RefTracker", () => {
+    describe("#setCallback", () => {
+        test("called with falsy value, no throw", () => {
+            // Arrange
+            const tracker = new RefTracker();
+
+            // Act
+            const underTest = () => tracker.setCallback(null);
+
+            // Assert
+            expect(underTest).not.toThrow();
+        });
+
+        test("called with non-function, throws", () => {
+            // Arrange
+            const tracker = new RefTracker();
+            const targetFn = (({}: any): CallbackFn);
+
+            // Act
+            const underTest = () => tracker.setCallback(targetFn);
+
+            // Assert
+            expect(underTest).toThrowErrorMatchingSnapshot();
+        });
+
+        describe("called with a function", () => {
+            test("no prior call to updateRef, does not call targetFn", () => {
+                // Arrange
+                const tracker = new RefTracker();
+                const targetFn = jest.fn();
+                // Act
+                tracker.setCallback(targetFn);
+
+                // Assert
+                expect(targetFn).not.toHaveBeenCalled();
+            });
+
+            test("prior updateRef call, target called with ref's node", async () => {
+                // Arrange
+                const tracker = new RefTracker();
+                const targetFn = jest.fn();
+                const ref = await new Promise((resolve) => {
+                    const nodes = (
+                        <View>
+                            <View ref={resolve} />
+                        </View>
+                    );
+                    mount(nodes);
+                });
+                const domNode = ReactDOM.findDOMNode(ref);
+                tracker.updateRef(ref);
+
+                // Act
+                tracker.setCallback(targetFn);
+
+                // Assert
+                expect(targetFn).toHaveBeenCalledWith(domNode);
+            });
+        });
+    });
+
+    describe("#updateRef", () => {
+        describe("calling without setting a callback", () => {
+            test("falsy ref, no throw", () => {
+                // Arrange
+                const tracker = new RefTracker();
+
+                // Act
+                const underTest = () => tracker.updateRef(null);
+
+                // Assert
+                expect(underTest).not.toThrow();
+            });
+
+            test("real ref, no callback, no throw", async () => {
+                // Arrange
+                const tracker = new RefTracker();
+                const ref = await new Promise((resolve) => {
+                    const nodes = (
+                        <View>
+                            <View ref={resolve} />
+                        </View>
+                    );
+                    mount(nodes);
+                });
+
+                // Act
+                const underTest = () => tracker.updateRef(ref);
+
+                // Assert
+                expect(underTest).not.toThrow();
+            });
+
+            test("real ref, targetFn callback, calls the targetFn", async () => {
+                // Arrange
+                const tracker = new RefTracker();
+                const targetFn = jest.fn();
+                tracker.setCallback(targetFn);
+
+                const ref = await new Promise((resolve) => {
+                    const nodes = (
+                        <View>
+                            <View ref={resolve} />
+                        </View>
+                    );
+                    mount(nodes);
+                });
+                const domNode = ReactDOM.findDOMNode(ref);
+
+                // Act
+                tracker.updateRef(ref);
+
+                // Assert
+                expect(targetFn).toHaveBeenCalledWith(domNode);
+            });
+
+            test("same ref, targetFn callback, does not call targetFn", async () => {
+                // Arrange
+                const tracker = new RefTracker();
+                const targetFn = jest.fn();
+                tracker.setCallback(targetFn);
+
+                const ref = await new Promise((resolve) => {
+                    const nodes = (
+                        <View>
+                            <View ref={resolve} />
+                        </View>
+                    );
+                    mount(nodes);
+                });
+                tracker.updateRef(ref);
+                targetFn.mockClear();
+
+                // Act
+                tracker.updateRef(ref);
+
+                // Assert
+                expect(targetFn).not.toHaveBeenCalled();
+            });
+        });
+    });
+});

package/src/util/active-tracker.js

@@ -0,0 +1,94 @@
+// @flow
+
+/**
+ * This interface should be implemented by types that are interested in the
+ * notifications of active state being stolen. Generally, this would also be
+ * subscribers that may also steal active state, but not necessarily.
+ *
+ * Once implemented, the type must call subscribe on a tracker to begin
+ * receiving notifications.
+ */
+export interface IActiveTrackerSubscriber {
+    /**
+     * Notification raised when something steals the active state from a
+     * subscribed tracker.
+     */
+    activeStateStolen: () => void;
+}
+
+/**
+ * This class is used to track the concept of active state (though technically
+ * that could be any boolean state). The tracker has a variety of subscribers
+ * that receive notifications of state theft and can steal the state.
+ *
+ * For the tooltip, this enables us to have a single tooltip active at any one
+ * time. The tracker allows tooltip anchors to coordinate which of them is
+ * active, and to ensure that if a different one becomes active, all the others
+ * know that they aren't.
+ *
+ * - When notified that the state has been stolen, subscribers can immediately
+ * reflect that theft (in the case of a tooltip, they would hide themselves).
+ * - The thief does not get notified if they were the one who stole the state
+ * since they should already know that they did that (this avoids having to have
+ * checks for reentrancy, for example).
+ * - When the subscriber that owns the state no longer needs it, it can
+ * voluntarily give it up.
+ * - If the state is stolen while a subscriber owns the
+ * state, that subscriber does not give up the state, as it doesn't have it
+ * anymore (it was stolen).
+ */
+export default class ActiveTracker {
+    _subscribers: Array<IActiveTrackerSubscriber> = [];
+    _active: boolean;
+
+    _getIndex(who: IActiveTrackerSubscriber): number {
+        return this._subscribers.findIndex((v) => v === who);
+    }
+
+    /**
+     * Called when a tooltip anchor becomes active so that it can tell all other
+     * anchors that they are no longer the active tooltip. Returns true if
+     * the there was a steal of active state from another anchor; otherwise, if
+     * no other anchor had been active, returns false.
+     */
+    steal(who: IActiveTrackerSubscriber): boolean {
+        const wasActive = !!this._active;
+        this._active = true;
+        for (const anchor of this._subscribers) {
+            if (anchor === who) {
+                // We don't need to notify the thief.
+                continue;
+            }
+            anchor.activeStateStolen();
+        }
+        return wasActive;
+    }
+
+    /**
+     * Called if a tooltip doesn't want to be active anymore.
+     * Should not be called when being told the active spot was stolen by
+     * another anchor, only when the anchor is unhovered and unfocused and they
+     * were active.
+     */
+    giveup() {
+        this._active = false;
+    }
+
+    /**
+     * Subscribes a tooltip anchor to the tracker so that it can be notified of
+     * steals. Returns a method that can be used to unsubscribe the anchor from
+     * notifications.
+     */
+    subscribe(who: IActiveTrackerSubscriber): () => void {
+        if (this._getIndex(who) >= 0) {
+            throw new Error("Already subscribed.");
+        }
+        this._subscribers.push(who);
+
+        const unsubscribe = () => {
+            const index = this._getIndex(who);
+            this._subscribers.splice(index, 1);
+        };
+        return unsubscribe;
+    }
+}

package/src/util/constants.js

@@ -0,0 +1,7 @@
+// @flow
+/**
+ * The attribute used to identify a tooltip portal.
+ */
+export const TooltipPortalAttributeName = "data-tooltip-portal";
+export const TooltipAppearanceDelay = 100;
+export const TooltipDisappearanceDelay = 75;

package/src/util/ref-tracker.js

@@ -0,0 +1,46 @@
+// @flow
+/**
+ * This is a little helper that we can use to wrap the react-popper reference
+ * update methods so that we can convert a regular React ref into a DOM node
+ * as react-popper expects, and also ensure we only update react-popper
+ * on actual changes, and not just renders of the same thing.
+ */
+import * as React from "react";
+import * as ReactDOM from "react-dom";
+
+import type {PopperChildrenProps} from "react-popper";
+import type {getRefFn} from "./types.js";
+
+type PopperRef = $PropertyType<PopperChildrenProps, "ref">;
+
+export default class RefTracker {
+    updateRef: getRefFn;
+    _lastRef: ?HTMLElement;
+    _targetFn: ?(?HTMLElement) => void;
+
+    updateRef: (ref: ?(React.Component<any> | Element)) => void = (ref) => {
+        if (ref) {
+            // We only want to update the reference if it is
+            // actually changed. Otherwise, we can trigger another render that
+            // would then update the reference again and just keep looping.
+            const domNode = ReactDOM.findDOMNode(ref);
+            if (domNode instanceof HTMLElement && domNode !== this._lastRef) {
+                this._lastRef = domNode;
+                this._targetFn && this._targetFn(domNode);
+            }
+        }
+    };
+
+    setCallback: (targetFn: ?PopperRef) => void = (targetFn) => {
+        if (this._targetFn !== targetFn) {
+            if (targetFn && typeof targetFn !== "function") {
+                throw new Error("targetFn must be a function");
+            }
+
+            this._targetFn = targetFn || null;
+            if (this._lastRef && this._targetFn) {
+                this._targetFn(this._lastRef);
+            }
+        }
+    };
+}

package/src/util/types.js

@@ -0,0 +1,29 @@
+// @flow
+import * as React from "react";
+
+export type getRefFn = (?(React.Component<any> | Element)) => void;
+
+export type Offset = {|
+    bottom: ?string,
+    top: ?string,
+    left: ?string,
+    right: ?string,
+    transform: ?string,
+|};
+
+export type Placement =
+    | "auto"
+    | "auto-start"
+    | "auto-end"
+    | "top"
+    | "top-start"
+    | "top-end"
+    | "bottom"
+    | "bottom-start"
+    | "bottom-end"
+    | "right"
+    | "right-start"
+    | "right-end"
+    | "left"
+    | "left-start"
+    | "left-end";