@internetarchive/bookreader 5.0.0-9 → 5.0.0-90

package/src/BookReader/utils.js

@@ -40,6 +40,24 @@ export function notInArray(value, array) {
   return !array.includes(value);
 }
 
+/**
+ * Determines the active element, going into shadow doms.
+ * @return {Element}
+ */
+export function getActiveElement(doc = document, recurseShadowDom = true) {
+  const activeElement = doc.activeElement;
+  if (recurseShadowDom && activeElement?.shadowRoot) {
+    return getActiveElement(activeElement.shadowRoot, true);
+  }
+  return activeElement;
+}
+
+/** Check if an input field/textarea is active. Also checks shadow DOMs. */
+export function isInputActive(doc = document) {
+  const activeEl = getActiveElement(doc);
+  return activeEl?.tagName == "INPUT" || activeEl?.tagName == "TEXTAREA";
+}
+
 /**
  * @param {HTMLIFrameElement} iframe
  * @return {Document}
@@ -80,16 +98,17 @@ export function encodeURIComponentPlus(value) {
 }
 
 /**
+ * @template {Function} T
  * Returns a function, that, as long as it continues to be invoked, will not
  * be triggered. The function will be called after it stops being called for
  * N milliseconds. If `immediate` is passed, trigger the function on the
  * leading edge, instead of the trailing.
  * @see https://davidwalsh.name/javascript-debounce-function
  *
- * @param {Function} func
+ * @param {T} func
  * @param {number} wait
  * @param {boolean} immediate
- * @return {Function}
+ * @return {T}
  */
 export function debounce(func, wait, immediate) {
   let timeout;
@@ -108,12 +127,13 @@ export function debounce(func, wait, immediate) {
 }
 
 /**
+ * @template T
  * Throttle function
  * @see https://remysharp.com/2010/07/21/throttling-function-calls
- * @param {Function} fn
+ * @param {T} fn
  * @param {number} threshold
  * @param {boolean} delay
- * @return {Function}
+ * @return {T}
  */
 export function throttle(fn, threshold, delay) {
   threshold || (threshold = 250);
@@ -160,14 +180,6 @@ export function PolyfilledCustomEvent(eventName, {bubbles = false, cancelable =
   return event;
 }
 
-/**
- * Promise based sleep - resolves at default 500ms
- * @param {Number} wait time in milliseconds
- */
-export function sleep(ms = 500) {
-  return new Promise(res => setTimeout(res(true), ms));
-}
-
 /*
  * Returns the number pixels something should be rendered at to be ~1n on the users
  * screen when measured with a ruler.
@@ -179,7 +191,110 @@ export function calcScreenDPI() {
   const dpi = el.offsetWidth;
   document.body.removeChild(el);
 
-  const screenDPI = dpi * devicePixelRatio;
+  // Do you believe in magic... numbers? We tested on some devices, and the displayed
+  // size of `width: 1in` was less than desired. On @pezvi's mac, it was ~75% ; on
+  // @cdrini's laptop it was ~85%. Since we want to avoid things appearing too small,
+  // let's just use a multiplier of 1.25
+  const screenDPI = dpi * 1.25;
   // This will return 0 in testing; never want it to be 0!
   return screenDPI == 0 ? 100 : screenDPI;
 }
+
+/**
+ * @param {number[]} nums
+ * @returns {number}
+ */
+export function sum(nums) {
+  return nums.reduce((cur, acc) => cur + acc, 0);
+}
+
+/**
+ * @template T
+ * @param {Generator<T>} gen
+ * @returns {T[]}
+ */
+export function genToArray(gen) {
+  const result = [];
+  for (const item of gen) {
+    result.push(item);
+  }
+  return result;
+}
+
+/**
+ * Check if arrays contain the same elements. Does reference comparison.
+ * @param {Array} arr1
+ * @param {Array} arr2
+ */
+export function arrEquals(arr1, arr2) {
+  return arr1.length == arr2.length && arr1.every((x, i) => x == arr2[i]);
+}
+
+/**
+ * Check if array has changed; namely to be used with lit's property.hasChanged
+ * @param {Array} [arr1]
+ * @param {Array} [arr2]
+ */
+export function arrChanged(arr1, arr2) {
+  return arr1 && arr2 && !arrEquals(arr1, arr2);
+}
+
+/**
+ * Waits the provided number of ms and then resolves with a promise
+ * @param {number} ms
+ **/
+export async function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * @template T
+ * @param {function(): T} fn
+ * @param {Object} options
+ * @param {function(T): boolean} [options.until]
+ * @return {T | undefined}
+ */
+export async function poll(fn, { step = 50, timeout = 500, until = val => Boolean(val), _sleep = sleep } = {}) {
+  const startTime = Date.now();
+  while (Date.now() - startTime < timeout) {
+    const result = fn();
+    if (until(result)) return result;
+    await _sleep(step);
+  }
+}
+
+/**
+ * Convert a EventTarget style event into a promise
+ * @param {EventTarget} target
+ * @param {string} eventType
+ * @return {Promise<Event>}
+ */
+export function promisifyEvent(target, eventType) {
+  return new Promise(res => {
+    const resolver = ev => {
+      target.removeEventListener(eventType, resolver);
+      res(ev);
+    };
+    target.addEventListener(eventType, resolver);
+  });
+}
+
+/**
+ * Escapes regex special characters in a string. Allows for safe usage in regexes.
+ * Src: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions
+ * @param {string} string
+ * @returns {string}
+ */
+export function escapeRegExp(string) {
+  return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
+}
+
+/**
+ * @param {number | 'fast' | 'slow' | string} speed
+ * Parsing of the jquery animation speed; see https://api.jquery.com/animate/
+ */
+export function parseAnimationSpeed(speed) {
+  if (speed === 'slow') return 600;
+  if (speed === 'fast') return 200;
+  return parseInt(speed, 10);
+}