first commit

test/unit/ui_utils_spec.js

@@ -0,0 +1,651 @@
+/* Copyright 2017 Mozilla Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  backtrackBeforeAllVisibleElements,
+  binarySearchFirstItem,
+  calcRound,
+  getPageSizeInches,
+  getVisibleElements,
+  isPortraitOrientation,
+  isValidRotation,
+  parseQueryString,
+  removeNullCharacters,
+} from "../../web/ui_utils.js";
+
+describe("ui_utils", function () {
+  describe("binary search", function () {
+    function isTrue(boolean) {
+      return boolean;
+    }
+    function isGreater3(number) {
+      return number > 3;
+    }
+
+    it("empty array", function () {
+      expect(binarySearchFirstItem([], isTrue)).toEqual(0);
+    });
+    it("single boolean entry", function () {
+      expect(binarySearchFirstItem([false], isTrue)).toEqual(1);
+      expect(binarySearchFirstItem([true], isTrue)).toEqual(0);
+    });
+    it("three boolean entries", function () {
+      expect(binarySearchFirstItem([true, true, true], isTrue)).toEqual(0);
+      expect(binarySearchFirstItem([false, true, true], isTrue)).toEqual(1);
+      expect(binarySearchFirstItem([false, false, true], isTrue)).toEqual(2);
+      expect(binarySearchFirstItem([false, false, false], isTrue)).toEqual(3);
+    });
+    it("three numeric entries", function () {
+      expect(binarySearchFirstItem([0, 1, 2], isGreater3)).toEqual(3);
+      expect(binarySearchFirstItem([2, 3, 4], isGreater3)).toEqual(2);
+      expect(binarySearchFirstItem([4, 5, 6], isGreater3)).toEqual(0);
+    });
+    it("three numeric entries and a start index", function () {
+      expect(binarySearchFirstItem([0, 1, 2, 3, 4], isGreater3, 2)).toEqual(4);
+      expect(binarySearchFirstItem([2, 3, 4], isGreater3, 2)).toEqual(2);
+      expect(binarySearchFirstItem([4, 5, 6], isGreater3, 1)).toEqual(1);
+    });
+  });
+
+  describe("isValidRotation", function () {
+    it("should reject non-integer angles", function () {
+      expect(isValidRotation()).toEqual(false);
+      expect(isValidRotation(null)).toEqual(false);
+      expect(isValidRotation(NaN)).toEqual(false);
+      expect(isValidRotation([90])).toEqual(false);
+      expect(isValidRotation("90")).toEqual(false);
+      expect(isValidRotation(90.5)).toEqual(false);
+    });
+
+    it("should reject non-multiple of 90 degree angles", function () {
+      expect(isValidRotation(45)).toEqual(false);
+      expect(isValidRotation(-123)).toEqual(false);
+    });
+
+    it("should accept valid angles", function () {
+      expect(isValidRotation(0)).toEqual(true);
+      expect(isValidRotation(90)).toEqual(true);
+      expect(isValidRotation(-270)).toEqual(true);
+      expect(isValidRotation(540)).toEqual(true);
+    });
+  });
+
+  describe("isPortraitOrientation", function () {
+    it("should be portrait orientation", function () {
+      expect(
+        isPortraitOrientation({
+          width: 200,
+          height: 400,
+        })
+      ).toEqual(true);
+
+      expect(
+        isPortraitOrientation({
+          width: 500,
+          height: 500,
+        })
+      ).toEqual(true);
+    });
+
+    it("should be landscape orientation", function () {
+      expect(
+        isPortraitOrientation({
+          width: 600,
+          height: 300,
+        })
+      ).toEqual(false);
+    });
+  });
+
+  describe("parseQueryString", function () {
+    it("should parse one key/value pair", function () {
+      const parameters = parseQueryString("key1=value1");
+      expect(parameters.size).toEqual(1);
+      expect(parameters.get("key1")).toEqual("value1");
+    });
+
+    it("should parse multiple key/value pairs", function () {
+      const parameters = parseQueryString(
+        "key1=value1&key2=value2&key3=value3"
+      );
+      expect(parameters.size).toEqual(3);
+      expect(parameters.get("key1")).toEqual("value1");
+      expect(parameters.get("key2")).toEqual("value2");
+      expect(parameters.get("key3")).toEqual("value3");
+    });
+
+    it("should parse keys without values", function () {
+      const parameters = parseQueryString("key1");
+      expect(parameters.size).toEqual(1);
+      expect(parameters.get("key1")).toEqual("");
+    });
+
+    it("should decode encoded key/value pairs", function () {
+      const parameters = parseQueryString("k%C3%ABy1=valu%C3%AB1");
+      expect(parameters.size).toEqual(1);
+      expect(parameters.get("këy1")).toEqual("valuë1");
+    });
+
+    it("should convert keys to lowercase", function () {
+      const parameters = parseQueryString("Key1=Value1&KEY2=Value2");
+      expect(parameters.size).toEqual(2);
+      expect(parameters.get("key1")).toEqual("Value1");
+      expect(parameters.get("key2")).toEqual("Value2");
+    });
+  });
+
+  describe("removeNullCharacters", function () {
+    it("should not modify string without null characters", function () {
+      const str = "string without null chars";
+      expect(removeNullCharacters(str)).toEqual("string without null chars");
+    });
+
+    it("should modify string with null characters", function () {
+      const str = "string\x00With\x00Null\x00Chars";
+      expect(removeNullCharacters(str)).toEqual("stringWithNullChars");
+    });
+
+    it("should modify string with non-displayable characters", function () {
+      const str = Array.from(
+        Array(32).keys(),
+        x => String.fromCharCode(x) + "a"
+      ).join("");
+      // \x00 is replaced by an empty string.
+      const expected =
+        "a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a";
+      expect(removeNullCharacters(str, /* replaceInvisible */ true)).toEqual(
+        expected
+      );
+    });
+  });
+
+  describe("getPageSizeInches", function () {
+    it("gets page size (in inches)", function () {
+      const page = {
+        view: [0, 0, 595.28, 841.89],
+        userUnit: 1.0,
+        rotate: 0,
+      };
+      const { width, height } = getPageSizeInches(page);
+
+      expect(+width.toPrecision(3)).toEqual(8.27);
+      expect(+height.toPrecision(4)).toEqual(11.69);
+    });
+
+    it("gets page size (in inches), for non-default /Rotate entry", function () {
+      const pdfPage1 = { view: [0, 0, 612, 792], userUnit: 1, rotate: 0 };
+      const { width: width1, height: height1 } = getPageSizeInches(pdfPage1);
+
+      expect(width1).toEqual(8.5);
+      expect(height1).toEqual(11);
+
+      const pdfPage2 = { view: [0, 0, 612, 792], userUnit: 1, rotate: 90 };
+      const { width: width2, height: height2 } = getPageSizeInches(pdfPage2);
+
+      expect(width2).toEqual(11);
+      expect(height2).toEqual(8.5);
+    });
+  });
+
+  describe("getVisibleElements", function () {
+    // These values are based on margin/border values in the CSS, but there
+    // isn't any real need for them to be; they just need to take *some* value.
+    const BORDER_WIDTH = 9;
+    const SPACING = 2 * BORDER_WIDTH - 7;
+
+    // This is a helper function for assembling an array of view stubs from an
+    // array of arrays of [width, height] pairs, which represents wrapped lines
+    // of pages. It uses the above constants to add realistic spacing between
+    // the pages and the lines.
+    //
+    // If you're reading a test that calls makePages, you should think of the
+    // inputs to makePages as boxes with no borders, being laid out in a
+    // container that has no margins, so that the top of the tallest page in
+    // the first row will be at y = 0, and the left of the first page in
+    // the first row will be at x = 0. The spacing between pages in a row, and
+    // the spacing between rows, is SPACING. If you wanted to construct an
+    // actual HTML document with the same layout, you should give each page
+    // element a margin-right and margin-bottom of SPACING, and add no other
+    // margins, borders, or padding.
+    //
+    // If you're reading makePages itself, you'll see a somewhat more
+    // complicated picture because this suite of tests is exercising
+    // getVisibleElements' ability to account for the borders that real page
+    // elements have. makePages tests this by subtracting a BORDER_WIDTH from
+    // offsetLeft/Top and adding it to clientLeft/Top. So the element stubs that
+    // getVisibleElements sees may, for example, actually have an offsetTop of
+    // -9. If everything is working correctly, this detail won't leak out into
+    // the tests themselves, and so the tests shouldn't use the value of
+    // BORDER_WIDTH at all.
+    function makePages(lines) {
+      const result = [];
+      let lineTop = 0,
+        id = 0;
+      for (const line of lines) {
+        const heights = line.map(pair => pair[1]);
+        const lineHeight = Math.max(...heights);
+        let offsetLeft = -BORDER_WIDTH;
+        for (const [clientWidth, clientHeight] of line) {
+          const offsetTop =
+            lineTop + (lineHeight - clientHeight) / 2 - BORDER_WIDTH;
+          const div = {
+            offsetLeft,
+            offsetTop,
+            clientWidth,
+            clientHeight,
+            clientLeft: BORDER_WIDTH,
+            clientTop: BORDER_WIDTH,
+          };
+          result.push({ id, div });
+          ++id;
+          offsetLeft += clientWidth + SPACING;
+        }
+        lineTop += lineHeight + SPACING;
+      }
+      return result;
+    }
+
+    // This is a reimplementation of getVisibleElements without the
+    // optimizations.
+    function slowGetVisibleElements(scroll, pages) {
+      const views = [],
+        ids = new Set();
+      const { scrollLeft, scrollTop } = scroll;
+      const scrollRight = scrollLeft + scroll.clientWidth;
+      const scrollBottom = scrollTop + scroll.clientHeight;
+      for (const view of pages) {
+        const { div } = view;
+        const viewLeft = div.offsetLeft + div.clientLeft;
+        const viewRight = viewLeft + div.clientWidth;
+        const viewTop = div.offsetTop + div.clientTop;
+        const viewBottom = viewTop + div.clientHeight;
+
+        if (
+          viewLeft < scrollRight &&
+          viewRight > scrollLeft &&
+          viewTop < scrollBottom &&
+          viewBottom > scrollTop
+        ) {
+          const minY = Math.max(0, scrollTop - viewTop);
+          const minX = Math.max(0, scrollLeft - viewLeft);
+
+          const hiddenHeight = minY + Math.max(0, viewBottom - scrollBottom);
+          const hiddenWidth = minX + Math.max(0, viewRight - scrollRight);
+
+          const fractionHeight =
+            (div.clientHeight - hiddenHeight) / div.clientHeight;
+          const fractionWidth =
+            (div.clientWidth - hiddenWidth) / div.clientWidth;
+          const percent = (fractionHeight * fractionWidth * 100) | 0;
+
+          let visibleArea = null;
+          if (percent < 100) {
+            visibleArea = {
+              minX,
+              minY,
+              maxX: Math.min(viewRight, scrollRight) - viewLeft,
+              maxY: Math.min(viewBottom, scrollBottom) - viewTop,
+            };
+          }
+
+          views.push({
+            id: view.id,
+            x: viewLeft,
+            y: viewTop,
+            view,
+            percent,
+            visibleArea,
+            widthPercent: (fractionWidth * 100) | 0,
+          });
+          ids.add(view.id);
+        }
+      }
+      return { first: views[0], last: views.at(-1), views, ids };
+    }
+
+    // This function takes a fixed layout of pages and compares the system under
+    // test to the slower implementation above, for a range of scroll viewport
+    // sizes and positions.
+    function scrollOverDocument(pages, horizontal = false, rtl = false) {
+      const sizes = pages.map(({ div }) =>
+        horizontal
+          ? Math.abs(div.offsetLeft + div.clientLeft + div.clientWidth)
+          : div.offsetTop + div.clientTop + div.clientHeight
+      );
+      const size = Math.max(...sizes);
+      // The numbers (7 and 5) are mostly arbitrary, not magic: increase them to
+      // make scrollOverDocument tests faster, decrease them to make the tests
+      // more scrupulous, and keep them coprime to reduce the chance of missing
+      // weird edge case bugs.
+      for (let i = -size; i < size; i += 7) {
+        // The screen height (or width) here (j - i) doubles on each inner loop
+        // iteration; again, this is just to test an interesting range of cases
+        // without slowing the tests down to check every possible case.
+        for (let j = i + 5; j < size; j += j - i) {
+          const scrollEl = horizontal
+            ? {
+                scrollTop: 0,
+                scrollLeft: i,
+                clientHeight: 10000,
+                clientWidth: j - i,
+              }
+            : {
+                scrollTop: i,
+                scrollLeft: 0,
+                clientHeight: j - i,
+                clientWidth: 10000,
+              };
+          expect(
+            getVisibleElements({
+              scrollEl,
+              views: pages,
+              sortByVisibility: false,
+              horizontal,
+              rtl,
+            })
+          ).toEqual(slowGetVisibleElements(scrollEl, pages));
+        }
+      }
+    }
+
+    it("with pages of varying height", function () {
+      const pages = makePages([
+        [
+          [50, 20],
+          [20, 50],
+        ],
+        [
+          [30, 12],
+          [12, 30],
+        ],
+        [
+          [20, 50],
+          [50, 20],
+        ],
+        [
+          [50, 20],
+          [20, 50],
+        ],
+      ]);
+      scrollOverDocument(pages);
+    });
+
+    it("widescreen challenge", function () {
+      const pages = makePages([
+        [
+          [10, 50],
+          [10, 60],
+          [10, 70],
+          [10, 80],
+          [10, 90],
+        ],
+        [
+          [10, 90],
+          [10, 80],
+          [10, 70],
+          [10, 60],
+          [10, 50],
+        ],
+        [
+          [10, 50],
+          [10, 60],
+          [10, 70],
+          [10, 80],
+          [10, 90],
+        ],
+      ]);
+      scrollOverDocument(pages);
+    });
+
+    it("works with horizontal scrolling", function () {
+      const pages = makePages([
+        [
+          [10, 50],
+          [20, 20],
+          [30, 10],
+        ],
+      ]);
+      scrollOverDocument(pages, /* horizontal = */ true);
+    });
+
+    it("works with horizontal scrolling with RTL-documents", function () {
+      const pages = makePages([
+        [
+          [-10, 50],
+          [-20, 20],
+          [-30, 10],
+        ],
+      ]);
+      scrollOverDocument(pages, /* horizontal = */ true, /* rtl = */ true);
+    });
+
+    it("handles `sortByVisibility` correctly", function () {
+      const scrollEl = {
+        scrollTop: 75,
+        scrollLeft: 0,
+        clientHeight: 750,
+        clientWidth: 1500,
+      };
+      const views = makePages([[[100, 150]], [[100, 150]], [[100, 150]]]);
+
+      const visible = getVisibleElements({ scrollEl, views });
+      const visibleSorted = getVisibleElements({
+        scrollEl,
+        views,
+        sortByVisibility: true,
+      });
+
+      const viewsOrder = [],
+        viewsSortedOrder = [];
+      for (const view of visible.views) {
+        viewsOrder.push(view.id);
+      }
+      for (const view of visibleSorted.views) {
+        viewsSortedOrder.push(view.id);
+      }
+      expect(viewsOrder).toEqual([0, 1, 2]);
+      expect(viewsSortedOrder).toEqual([1, 2, 0]);
+    });
+
+    it("handles views being empty", function () {
+      const scrollEl = {
+        scrollTop: 10,
+        scrollLeft: 0,
+        clientHeight: 750,
+        clientWidth: 1500,
+      };
+      const views = [];
+
+      expect(getVisibleElements({ scrollEl, views })).toEqual({
+        first: undefined,
+        last: undefined,
+        views: [],
+        ids: new Set(),
+      });
+    });
+
+    it("handles all views being hidden (without errors)", function () {
+      const scrollEl = {
+        scrollTop: 100000,
+        scrollLeft: 0,
+        clientHeight: 750,
+        clientWidth: 1500,
+      };
+      const views = makePages([[[100, 150]], [[100, 150]], [[100, 150]]]);
+
+      expect(getVisibleElements({ scrollEl, views })).toEqual({
+        first: undefined,
+        last: undefined,
+        views: [],
+        ids: new Set(),
+      });
+    });
+
+    // This sub-suite is for a notionally internal helper function for
+    // getVisibleElements.
+    describe("backtrackBeforeAllVisibleElements", function () {
+      // Layout elements common to all tests
+      const tallPage = [10, 50];
+      const shortPage = [10, 10];
+
+      // A scroll position that ensures that only the tall pages in the second
+      // row are visible
+      const top1 =
+        20 +
+        SPACING + // height of the first row
+        40; // a value between 30 (so the short pages on the second row are
+      // hidden) and 50 (so the tall pages are visible)
+
+      // A scroll position that ensures that all of the pages in the second row
+      // are visible, but the tall ones are a tiny bit cut off
+      const top2 =
+        20 +
+        SPACING + // height of the first row
+        10; // a value greater than 0 but less than 30
+
+      // These tests refer to cases enumerated in the comments of
+      // backtrackBeforeAllVisibleElements.
+      it("handles case 1", function () {
+        const pages = makePages([
+          [
+            [10, 20],
+            [10, 20],
+            [10, 20],
+            [10, 20],
+          ],
+          [tallPage, shortPage, tallPage, shortPage],
+          [
+            [10, 50],
+            [10, 50],
+            [10, 50],
+            [10, 50],
+          ],
+          [
+            [10, 20],
+            [10, 20],
+            [10, 20],
+            [10, 20],
+          ],
+          [[10, 20]],
+        ]);
+        // binary search would land on the second row, first page
+        const bsResult = 4;
+        expect(
+          backtrackBeforeAllVisibleElements(bsResult, pages, top1)
+        ).toEqual(4);
+      });
+
+      it("handles case 2", function () {
+        const pages = makePages([
+          [
+            [10, 20],
+            [10, 20],
+            [10, 20],
+            [10, 20],
+          ],
+          [tallPage, shortPage, tallPage, tallPage],
+          [
+            [10, 50],
+            [10, 50],
+            [10, 50],
+            [10, 50],
+          ],
+          [
+            [10, 20],
+            [10, 20],
+            [10, 20],
+            [10, 20],
+          ],
+        ]);
+        // binary search would land on the second row, third page
+        const bsResult = 6;
+        expect(
+          backtrackBeforeAllVisibleElements(bsResult, pages, top1)
+        ).toEqual(4);
+      });
+
+      it("handles case 3", function () {
+        const pages = makePages([
+          [
+            [10, 20],
+            [10, 20],
+            [10, 20],
+            [10, 20],
+          ],
+          [tallPage, shortPage, tallPage, shortPage],
+          [
+            [10, 50],
+            [10, 50],
+            [10, 50],
+            [10, 50],
+          ],
+          [
+            [10, 20],
+            [10, 20],
+            [10, 20],
+            [10, 20],
+          ],
+        ]);
+        // binary search would land on the third row, first page
+        const bsResult = 8;
+        expect(
+          backtrackBeforeAllVisibleElements(bsResult, pages, top1)
+        ).toEqual(4);
+      });
+
+      it("handles case 4", function () {
+        const pages = makePages([
+          [
+            [10, 20],
+            [10, 20],
+            [10, 20],
+            [10, 20],
+          ],
+          [tallPage, shortPage, tallPage, shortPage],
+          [
+            [10, 50],
+            [10, 50],
+            [10, 50],
+            [10, 50],
+          ],
+          [
+            [10, 20],
+            [10, 20],
+            [10, 20],
+            [10, 20],
+          ],
+        ]);
+        // binary search would land on the second row, first page
+        const bsResult = 4;
+        expect(
+          backtrackBeforeAllVisibleElements(bsResult, pages, top2)
+        ).toEqual(4);
+      });
+    });
+  });
+
+  describe("calcRound", function () {
+    it("should handle different browsers/environments correctly", function () {
+      if (
+        typeof window !== "undefined" &&
+        window.navigator?.userAgent?.includes("Firefox")
+      ) {
+        expect(calcRound(1.6)).not.toEqual(1.6);
+      } else {
+        expect(calcRound(1.6)).toEqual(1.6);
+      }
+    });
+  });
+});