@khanacademy/perseus 3.0.0 → 4.0.0

package/src/components/highlighting/highlightable-content.jsx

@@ -1,245 +0,0 @@
-// @flow
-/**
- * The entry point for highlighting!
- *
- * Given a content node and a set of serialized highlights, this component
- * renders the content with the given highlights applied. The content's DOM is
- * not modified by this process, so any content should be safe to pass to this
- * component.
- *
- * This component also renders controls for the user to add/remove/update
- * highlights. When the user does so, this component will update the full set
- * of highlights, serialize them, and call `onSerializedHighlightsUpdate` with
- * new set of serialized highlights, which you can then persist and send back
- * down to this component. Easy peasy!
- */
-import {StyleSheet, css} from "aphrodite";
-import * as React from "react";
-
-import {
-    addHighlight,
-    buildHighlight,
-    deserializeHighlight,
-    serializeHighlight,
-} from "./highlights.js";
-import HighlightingUI from "./ui/highlighting-ui.jsx";
-import WordIndexer from "./word-indexer.jsx";
-
-import type {
-    DOMHighlight,
-    DOMHighlightSet,
-    SerializedHighlightSet,
-    DOMRange,
-} from "./types.js";
-
-type HighlightableContentProps = {
-    // The highlightable content itself. Highlights will be defined relative to
-    // the content specified here.
-    children?: React.Element<any>,
-    // Whether the highlights are user-editable. If false, highlights are
-    // read-only.
-    editable: boolean,
-    // Whether highlighting is currently enabled. If false, highlights are not
-    // visible and are read-only (regardless of the `editable` prop), and this
-    // component is effectively a no-op.
-    //
-    // NOTE(mdr): The purpose of the `enabled` prop, as opposed to, say, just
-    //     *not* wrapping the content, is to enable quick toggles between
-    //     enabled/disabled while maintaining the same component structure.
-    //     Forcing React to rebuild the entire component tree is not kind!
-    enabled: boolean,
-    // When the user attempts to add/remove/update a highlight, this callback
-    // will be called with a newly-updated full set of highlights that reflects
-    // the user's intent.
-    onSerializedHighlightsUpdate: (
-        serializedHighlights: SerializedHighlightSet,
-    ) => mixed,
-    // The set of highlights to apply to the given content.
-    serializedHighlights: SerializedHighlightSet,
-    ...
-};
-
-type HighlightableContentState = {
-    // A cached list of DOMRanges, each representing one of the content's
-    // semantic words. Sorted in document order.
-    wordRanges: $ReadOnlyArray<DOMRange>,
-    ...
-};
-
-class HighlightableContent extends React.PureComponent<
-    HighlightableContentProps,
-    HighlightableContentState,
-> {
-    // References to the mounted container and content divs.
-    _container: ?HTMLElement;
-    _content: ?HTMLElement;
-
-    state: HighlightableContentState = {
-        wordRanges: [],
-    };
-
-    _buildHighlight(highlightRange: DOMRange): ?DOMHighlight {
-        // TODO(mdr): If _buildHighlight starts getting called more often, we
-        //     might want to cache the DOMHighlightSet instead of recomputing
-        //     it here.
-        return buildHighlight(
-            this._getDOMHighlights(),
-            this.state.wordRanges,
-            highlightRange,
-        );
-    }
-
-    /**
-     * Take the highlights from props, and deserialize them into DOMHighlights,
-     * according to the latest cache of word ranges.
-     */
-    _getDOMHighlights(): DOMHighlightSet {
-        const {serializedHighlights} = this.props;
-        const {wordRanges} = this.state;
-
-        const domHighlights = {};
-        for (const key of Object.keys(serializedHighlights)) {
-            domHighlights[key] = deserializeHighlight(
-                serializedHighlights[key],
-                wordRanges,
-            );
-        }
-        return domHighlights;
-    }
-
-    /**
-     * Add the given DOMHighlight to the current set.
-     */
-    _handleAddHighlight: (highlight: DOMHighlight) => void = (
-        highlight: DOMHighlight,
-    ) => {
-        const newDomHighlights = addHighlight(
-            this._getDOMHighlights(),
-            highlight,
-        );
-
-        const newSerializedHighlights = {};
-        for (const key of Object.keys(newDomHighlights)) {
-            newSerializedHighlights[key] = serializeHighlight(
-                newDomHighlights[key],
-            );
-        }
-
-        this.props.onSerializedHighlightsUpdate(newSerializedHighlights);
-    };
-
-    /**
-     * Remove the given highlight from the list, and call our callback with the
-     * new set of highlights.
-     */
-    _handleRemoveHighlight: (keyToRemove: string) => void = (
-        keyToRemove: string,
-    ) => {
-        const {serializedHighlights} = this.props;
-        const newSerializedHighlights = {...serializedHighlights};
-        delete newSerializedHighlights[keyToRemove];
-        this.props.onSerializedHighlightsUpdate(newSerializedHighlights);
-    };
-
-    /**
-     * When our WordIndexer sends us a new cache of word ranges, store it in
-     * our component state.
-     */
-    _handleWordsUpdate: (wordRanges: $ReadOnlyArray<DOMRange>) => void = (
-        wordRanges: $ReadOnlyArray<DOMRange>,
-    ) => {
-        this.setState({wordRanges});
-    };
-
-    render(): React.Element<"div"> {
-        const highlights = this._getDOMHighlights();
-
-        // NOTE(mdr): This lambda is rebuilt every time this component updates,
-        //     so every update to HighlightableContent triggers an update in
-        //     the child HighlightingUI and SelectionTracker, even if the
-        //     behavior hasn't changed.
-        //
-        //     Over-updating is preferable to under-updating here, because some
-        //     updates in this component's props/state *do* affect
-        //     `buildHighlight`'s behavior, and *should* trigger an update.
-        //
-        //     A more performant approach would be to cache this function
-        //     object until its implicitly-bound inputs change. If profiling
-        //     leads us to implement such caching, this draft might be a good
-        //     starting point: https://phabricator.khanacademy.org/D35623?id=170698
-        const buildHighlight = (r: DOMRange) => this._buildHighlight(r);
-
-        return (
-            <div
-                className={css(styles.container)}
-                ref={(container) => (this._container = container)}
-            >
-                <div>
-                    {this.props.enabled && this._container && this._content && (
-                        <HighlightingUI
-                            buildHighlight={buildHighlight}
-                            contentNode={this._content}
-                            editable={this.props.editable}
-                            highlights={highlights}
-                            offsetParent={this._container}
-                            zIndexes={{
-                                // The content has a z-index of 1, so, to
-                                // be below the content, use z-index of 0.
-                                //
-                                // TODO(mdr): Is this way of passing around
-                                //     `z-index: 0` actually worth the
-                                //     trouble? We used to have more, but
-                                //     now we don't need them...
-                                belowContent: 0,
-                            }}
-                            onAddHighlight={this._handleAddHighlight}
-                            onRemoveHighlight={this._handleRemoveHighlight}
-                        />
-                    )}
-                </div>
-                <div
-                    className={css(styles.content)}
-                    ref={(content) => (this._content = content)}
-                >
-                    <WordIndexer onWordsUpdate={this._handleWordsUpdate}>
-                        {this.props.children}
-                    </WordIndexer>
-                </div>
-            </div>
-        );
-    }
-}
-
-const styles = StyleSheet.create({
-    // We render content with z-index 1, and highlights with z-index 0, so that
-    // content will receive the browser's native pointer events. (Highlights
-    // have their own magic code to manage hover detection, despite being
-    // behind the content.)
-
-    container: {
-        // Position the container and give it a z-index, to scope the z-indexes
-        // inside by creating a stacking context.
-        // https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/The_stacking_context
-        //
-        // This way, content's z-index of 1, and highlights' z-index of 0, and
-        // tooltips' z-index of 2 don't interact with anything external;
-        // external UI will see `HighlightableContent` as a single flat layer
-        // with a z-index of 0. This removes the need for us to coordinate our
-        // choices of z-index with external UI.
-        position: "relative",
-        zIndex: 0,
-    },
-
-    content: {
-        // NOTE(mdr): Creating a stacking context for content of z-index 1 may
-        //    be problematic if the content and external page want to
-        //    interleave layers between each other, e.g., if the application UI
-        //    wants to render something above some parts of our content, but
-        //    below other parts. It's not relevant for the current Passage-only
-        //    call site, but could be relevant someday…
-        position: "relative",
-        zIndex: 1,
-    },
-});
-
-export default HighlightableContent;

package/src/components/highlighting/highlights.js

@@ -1,208 +0,0 @@
-// @flow
-/**
- * Utility functions for manipulating highlights.
- */
-
-import {Errors} from "../../logging/log.js";
-import {PerseusError} from "../../perseus-error.js";
-
-import {
-    findFirstAndLastWordIndexes,
-    unionRanges,
-    spanRanges,
-    rangeIncludes,
-} from "./ranges.js";
-
-import type {
-    DOMHighlight,
-    DOMHighlightSet,
-    SerializedHighlight,
-    DOMRange,
-} from "./types.js";
-
-/**
- * Given a list of DOMHighlights, return a new list that also includes the
- * given DOMRange as a new DOMHighlight. If the DOMHighlight intersects
- * existing DOMHighlights, the other Highlights are removed and their ranges
- * are merged into the new DOMHighlight.
- */
-export function addHighlight(
-    existingHighlights: DOMHighlightSet,
-    newHighlight: DOMHighlight,
-): DOMHighlightSet {
-    const newHighlights = {};
-
-    // Merge the new highlight with any existing highlights that intersect it.
-    let mergedDomRange = newHighlight.domRange;
-    let mergedFirstWordIndex = newHighlight.firstWordIndex;
-    let mergedLastWordIndex = newHighlight.lastWordIndex;
-    for (const key of Object.keys(existingHighlights)) {
-        const h = existingHighlights[key];
-        const newMergedDomRange = unionRanges(h.domRange, mergedDomRange);
-        if (newMergedDomRange) {
-            // This highlight's range was successfully merged into the new
-            // highlight. Update `mergedDomRange`, and *don't* add it to the
-            // new set of highlights.
-            mergedDomRange = newMergedDomRange;
-            mergedFirstWordIndex = Math.min(
-                h.firstWordIndex,
-                mergedFirstWordIndex,
-            );
-            mergedLastWordIndex = Math.max(
-                h.lastWordIndex,
-                mergedLastWordIndex,
-            );
-        } else {
-            // This highlight's range can't be merged into the new highlight.
-            // Add it to the new set of highlights.
-            newHighlights[key] = h;
-        }
-    }
-
-    const newMergedHighlight = {
-        firstWordIndex: mergedFirstWordIndex,
-        lastWordIndex: mergedLastWordIndex,
-        domRange: mergedDomRange,
-    };
-
-    // Add the newly-merged highlight to the set of highlights, under a new,
-    // unique key.
-    const existingKeys = Object.keys(newHighlights);
-    const newKey = createNewUniqueKey(existingKeys);
-    newHighlights[newKey] = newMergedHighlight;
-
-    return newHighlights;
-}
-
-/**
- * Given a DOMRange and a list of word ranges, build a corresponding
- * DOMHighlight.
- *
- * If the DOMRange is not a valid highlight given the word ranges, return null.
- */
-export function buildHighlight(
-    existingHighlights: DOMHighlightSet,
-    wordRanges: $ReadOnlyArray<DOMRange>,
-    newHighlightRange: DOMRange,
-): ?DOMHighlight {
-    // If any existing highlight fully contains the new highlight range, it's
-    // redundant and therefore not valid to build this as a highlight.
-    // Return null.
-    //
-    // NOTE(mdr): Really, our goal is to determine whether the new range's
-    //     content is already fully highlighted, so you could imagine this
-    //     logic not catching the case where a range's contents are fully
-    //     highlighted, but by multiple ranges.
-    //
-    //     However, words aren't actually adjacent; they have spaces between
-    //     them. So, even if each word in the range is currently highlighted,
-    //     the space between a pair of words will only be highlighted if
-    //     they're included in the same highlight range.
-    //
-    //     Therefore, if this new range isn't fully contained by an existing
-    //     highlight, then there's at *least* an unhighlighted space within the
-    //     range. In that case, it makes sense to offer this as a new highlight
-    //     that, when added, will merge with the highlights that it intersects.
-    for (const key of Object.keys(existingHighlights)) {
-        const existingHighlightRange = existingHighlights[key].domRange;
-        if (rangeIncludes(existingHighlightRange, newHighlightRange)) {
-            return null;
-        }
-    }
-
-    // If the new highlight range doesn't span two words from the content, it's
-    // not valid to build this as a highlight. Return null.
-    const indexes = findFirstAndLastWordIndexes(newHighlightRange, wordRanges);
-    if (!indexes) {
-        return null;
-    }
-
-    const [firstWordIndex, lastWordIndex] = indexes;
-    const firstWord = wordRanges[firstWordIndex];
-    const lastWord = wordRanges[lastWordIndex];
-    return {
-        firstWordIndex,
-        lastWordIndex,
-        domRange: spanRanges(firstWord, lastWord),
-    };
-}
-
-/**
- * Given a list of keys, return a new unique key that is not in the list.
- */
-function createNewUniqueKey(existingKeys: $ReadOnlyArray<string>): string {
-    // The base of the key is the current time, in milliseconds since epoch.
-    const base = `${new Date().getTime()}`;
-    if (!existingKeys.includes(base)) {
-        return base;
-    }
-
-    // But, if the user is a fast-clicker or time-traveler or something, and
-    // already has a highlight from this millisecond, then let's attach a
-    // suffix and keep incrementing it until we find an unused suffix.
-    let suffix = 0;
-    let key;
-    do {
-        key = `${base}-${suffix}`;
-        suffix++;
-    } while (existingKeys.includes(key));
-
-    return key;
-}
-
-/**
- * Given a SerializedHightlight and the current set of word ranges, return a
- * DOMHighlight representing the SerializedHighlight.
- *
- * If the SerializedHighlight is not valid given the list of word ranges, throw
- * an error.
- */
-export function deserializeHighlight(
-    serializedHighlight: SerializedHighlight,
-    wordRanges: $ReadOnlyArray<DOMRange>,
-): DOMHighlight {
-    const {firstWordIndex, lastWordIndex} = serializedHighlight.range;
-
-    const firstWord = wordRanges[firstWordIndex];
-    if (!firstWord) {
-        throw new PerseusError(
-            `first word index ${firstWord} is out of bounds: ` +
-                `must be 0–${wordRanges.length - 1} inclusive`,
-            Errors.InvalidInput,
-            {metadata: {firstWord, wordRanges: JSON.stringify(wordRanges)}},
-        );
-    }
-
-    const lastWord = wordRanges[lastWordIndex];
-    if (!lastWord) {
-        throw new PerseusError(
-            `last word index ${lastWord} is out of bounds: ` +
-                `must be 0–${wordRanges.length - 1} inclusive`,
-            Errors.InvalidInput,
-            {metadata: {lastWord, wordRanges: JSON.stringify(wordRanges)}},
-        );
-    }
-
-    return {
-        firstWordIndex,
-        lastWordIndex,
-        domRange: spanRanges(firstWord, lastWord),
-    };
-}
-
-/**
- * Return a SerializedHighlight representing the given DOMHighlight.
- */
-export function serializeHighlight(
-    highlight: DOMHighlight,
-): SerializedHighlight {
-    const {firstWordIndex, lastWordIndex} = highlight;
-
-    return {
-        range: {
-            type: "word-indexes",
-            firstWordIndex,
-            lastWordIndex,
-        },
-    };
-}