keymanapp · mcdurdin · Dec 14, 2023 · Oct 30, 2023 · Oct 30, 2023 · Oct 30, 2023
@@ -1,8 +1,8 @@
+<!DOCTYPE html>
 <html>
 <!--
  Copyright (C) 2017-2019 SIL International. All rights reserved.
 -->
-
 <head>
   <meta http-equiv="content-type" content="text/html; charset=UTF-8">
   <meta name="viewport" content="width=device-width, user-scalable=no">
@@ -15,6 +15,7 @@
        polyfill.
   -->
   <script src="es6-shim.min.js"></script>
+  <script src="other-polyfills.js"></script>
   <script src="keymanweb-webview.js"></script>
   <script src="sentry.min.js"></script>
   <script src="keyman-sentry.js"></script>

@@ -0,0 +1,17 @@
+// Needed by the KMW's gesture engine until Chrome 61.
+var DOMRect = DOMRect || function (x, y, width, height) {
+  this.x = this.left = x;
+  this.y = this.top = y;
+  this.width = width;
+  this.height = height;
+  this.bottom = y + height;
+  this.right = x + width;
+};
+
+// https://stackoverflow.com/questions/53308396/how-to-polyfill-array-prototype-includes-for-ie8
+if(!Array.prototype.includes){
+  //or use Object.defineProperty
+  Array.prototype.includes = function(search){
+   return !!~this.indexOf(search);
+ }
+}
@@ -297,6 +297,7 @@ public String toString() {
   protected static final String KMFilename_KmwGlobeHintCss = "globe-hint.css";
   protected static final String KMFilename_Osk_Ttf_Font = "keymanweb-osk.ttf";
   protected static final String KMFilename_JSPolyfill = "es6-shim.min.js";
+  protected static final String KMFilename_JSPolyfill2 = "other-polyfills.js";
 
   // Deprecated by KeyboardController.KMFilename_Installed_KeyboardsList
   public static final String KMFilename_KeyboardsList = "keyboards_list.dat";
@@ -864,6 +865,7 @@ private static void copyAssets(Context context) {
       // Copy default keyboard font
       copyAsset(context, KMDefault_KeyboardFont, "", true);
       copyAsset(context, KMFilename_JSPolyfill, "", true);
+      copyAsset(context, KMFilename_JSPolyfill2, "", true);
 
       // Keyboard packages directory
       File packagesDir = new File(getPackagesDir());

@@ -18,20 +18,35 @@ export default class PriorityQueue<Type> {
   private comparator: Comparator<Type>;
   private heap: Type[];
 
+  /**
+   * Shallow-copy / clone constructor.
+   * @param instance
+   */
+  constructor(instance: PriorityQueue<Type>);
   /**
    * Constructs an empty priority queue.
    * @param comparator A `Comparator` returning negative values when and only when
    * the first parameter should precede the second parameter.
+   * @param initialEntries
    */
-  constructor(comparator: Comparator<Type>, initialEntries: Type[] = []) {
+  constructor(comparator: Comparator<Type>, initialEntries?: Type[]);
+  constructor(arg1: Comparator<Type> | PriorityQueue<Type>, initialEntries?: Type[]) {
+    if(typeof arg1 != 'function') {
+      this.comparator = arg1.comparator;
+      // Shallow-copies are fine.
+      this.heap = ([] as Type[]).concat(arg1.heap);
+      return;
+    }
+
+    const comparator = arg1;
     // TODO: We may wish to allow options specifying a limit or threshold for adding
     // items to the priority queue.  Possibly both.
     //
     // When that time comes, consider a min-max heap.
     // https://en.wikipedia.org/wiki/Min-max_heap
     this.comparator = comparator;
 
-    this.heap = Array.from(initialEntries);
+    this.heap = Array.from(initialEntries ?? []);
     this.heapify();
   }
 

@@ -58,7 +58,7 @@
     "karma-teamcity-reporter": "^1.1.0",
     "mocha": "^10.0.0",
     "mocha-teamcity-reporter": "^4.0.0",
-    "sinon": "^7.1.1",
+    "sinon": "^14.0.0",
     "ts-node": "^10.9.1",
     "typescript": "^4.9.5"
   },

@@ -107,7 +107,10 @@ module.exports = function(baseConfigParams  /* the project's base configuration
     FINAL_LAUNCHER_DEFS = mergeLaunchers( PRIMARY_LAUNCHERS,
                                           SECONDARY_LAUNCHERS);
   } else {
-    FINAL_LAUNCHER_DEFS = PRIMARY_LAUNCHERS;
+    // The function also does some necessary bookkeeping that makes for
+    // cleaner definitions at the file's top, so we call it even if we
+    // aren't merging lists.
+    FINAL_LAUNCHER_DEFS = mergeLaunchers(PRIMARY_LAUNCHERS);
   }
 
   var FINAL_BROWSER_LIST = toBrowserList(FINAL_LAUNCHER_DEFS);

@@ -15,7 +15,7 @@ export const pluginForDowncompiledClassTreeshaking: esbuild.Plugin = {
       return {
         // Marks any classes compiled by TS (as per the /** @class */ annotation)
         // as __PURE__ in order to facilitate tree-shaking.
-        contents: source.replace('/** @class */', '/* @__PURE__ */ /** @class */'),
+        contents: source.replaceAll('/** @class */', '/** @__PURE__ */'),
         loader: 'js'
       }
     });

@@ -96,6 +96,8 @@ export async function determineNeededDowncompileHelpers(config: esbuild.BuildOpt
               detectedHelpers.push('__createBinding');
             } else if(helper == '__exportStar') {
               detectedHelpers.push('__createBinding');
+            } else if(helper == '__spread') {
+              detectedHelpers.push('__read');
             }
           }
         }

@@ -0,0 +1,18 @@
+{
+  "check-coverage": false,
+  "clean": true,
+  "exclude": [
+    "src/test/*",
+    "node_modules/*",
+    "src/tools/*"
+  ],
+  "exclude-after-remap": true,
+  "include": [
+    "src/engine/headless/*"
+  ],
+  "reporter": ["text", "text-summary"],
+  "reports-dir": "build/coverage",
+  "src": [
+    "src/engine/headless/*"
+  ]
+}
@@ -0,0 +1,11 @@
+# Build products
+build
+
+# Legacy build folders.
+
+# Other local files.
+node_modules/
+unit_tests/modernizr.js
+.idea/**/*.xml
+*.iml
+*.kpj.user
@@ -0,0 +1,5 @@
+import { fileURLToPath } from "url";
+import { dirname } from 'path';
+
+// Tells ts-node where to find the tsconfig.json to be used for executing TS unit tests.
+process.env.TS_NODE_PROJECT = `${dirname(fileURLToPath(import.meta.url))}/src/test/auto/tsconfig.json`;
@@ -0,0 +1,10 @@
+{
+  "extensions": ["js", "ts"],
+  "spec" : [
+    "src/test/auto/headless/**/*.*"
+  ],
+  "node-option": [
+    "loader=ts-node/esm"
+  ],
+  "require": ".mocharc.env.js"
+}
@@ -0,0 +1,11 @@
+# Keyman:  Gesture Recognizer Module
+The Original Code is (C) SIL International
+
+The Gesture Recognizer module is an internal component for all of Keyman's Web-based OSKs.  At this time, this is only referenced by
+KeymanWeb, seen within this repo at /web/.
+
+## Minimum Compilation Requirements
+
+See the repo-level [document for build configuration](../../../docs/build/index.md) for details on how to
+configure your build environment.
+- Follow the Keyman Engine for Web (KeymanWeb) requirements where appropriate.
@@ -0,0 +1,7 @@
+import esbuild from 'esbuild';
+import { esmConfiguration, bundleObjEntryPoints, prepareTslibTreeshaking } from '../es-bundling/build/index.mjs';
+
+await esbuild.build(await prepareTslibTreeshaking({
+  ...esmConfiguration,
+  ...bundleObjEntryPoints('lib', 'build/obj/index.js')
+}));
@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+
+## START STANDARD BUILD SCRIPT INCLUDE
+# adjust relative paths as necessary
+THIS_SCRIPT="$(greadlink -f "${BASH_SOURCE[0]}" 2>/dev/null || readlink -f "${BASH_SOURCE[0]}")"
+. "$(dirname "$THIS_SCRIPT")/../../../resources/build/build-utils.sh"
+## END STANDARD BUILD SCRIPT INCLUDE
+
+. "$KEYMAN_ROOT/resources/shellHelperFunctions.sh"
+
+# This script runs from its own folder
+cd "$(dirname "$THIS_SCRIPT")"
+
+################################ Main script ################################
+
+builder_describe "Builds the gesture-recognition model for Web-based on-screen keyboards" \
+  "@/common/web/es-bundling build" \
+  "@/common/web/utils build" \
+  "clean" \
+  "configure" \
+  "build" \
+  "test" \
+  ":module" \
+  ":tools  tools for testing & developing test resources for this module" \
+  "--ci    sets the --ci option for child scripts (i.e, the $(builder_term test) action)"
+
+builder_describe_outputs \
+  configure        /node_modules \
+  build:module     /common/web/gesture-recognizer/build/lib/index.mjs \
+  build:tools      /common/web/gesture-recognizer/build/tools/lib/index.mjs
+
+builder_parse "$@"
+
+# TODO: build if out-of-date if test is specified
+# TODO: configure if npm has not been run, and build is specified
+
+if builder_start_action configure; then
+  verify_npm_setup
+  builder_finish_action success configure
+fi
+
+if builder_start_action clean; then
+  rm -rf build/
+  builder_finish_action success clean
+fi
+
+if builder_start_action build:module; then
+  # Build
+  tsc --build $builder_verbose
+  node build-bundler.js
+  builder_finish_action success build:module
+fi
+
+if builder_start_action build:tools; then
+  src/tools/build.sh build
+  builder_finish_action success build:tools
+fi
+
+if builder_start_action test:module; then
+  if builder_has_option --ci; then
+    ./test.sh --ci
+  else
+    ./test.sh
+  fi
+  builder_finish_action success test:module
+fi
+
+if builder_has_action test:tools && ! builder_has_action test:module; then
+  echo "The $(builder_term test:tools) action is currently a no-op."
+fi
@@ -0,0 +1,67 @@
+# GestureRecognizer - DOM configuration design
+
+The design for `GestureRecognizer`'s configuration object is based upon the needs and logic
+of the on-screen keyboard (the "OSK") as implemented in Keyman Engine for Web 15.0.
+Much of its related code is strewn about in various places there; one of the benefits of
+developing this module has been to better document the behavior and produce an explicit
+abstraction that can both centralize and clarify it.
+
+While many doc-comments have been added to the configuration object's code, a bit more
+overview may yet be merited here.
+
+## On "safe zones" and "safe zone padding"
+
+For modeling cancellation of an ongoing touchpoint or cursor-based input sequence, our design
+considers it important to have coordinate boundaries that may actually be crossed.  This is
+notably complicated by certain use cases.
+
+Consider implementation of an OSK that completely fills a WebView in a mobile application -
+we actually use this in Keyman for Android and in Keyman for iPhone and iPad.  Without any
+defined "safe zone", it is impossible for a touchpoint within the WebView to actually leave
+this OSK's boundaries.  Should the user's finger attempt to leave those boundaries... it
+leaves the viewport entirely - and quite possibly, the physical boundaries of the device's
+touchscreen!
+
+To facilitate this, we have implemented a "safe zone" of sorts, traditionally based on the
+available viewport.  Should a touchpoint cross the boundary of the safe zone - and thus,
+become very close to a device boundary - that may then be used as criteria for a cancellation.
+In reference to the [demo/host page](../../../../web/testing/gesture-recognizer/), this is
+visualized as the outer, darker-colored set of dashed lines nested closely to the emulated
+device borders.
+
+However!  What if the user _starts_ their input sequence very close to the safe zone?
+Especially with touch-based input, there can be natural shifts in position of the input point
+that may accidentally cross that boundary... and it is entirely possible to _start_ in an
+"unsafe" area.  To prevent this from auto-canceling user input in these scenarios, we have
+also noted a need for "safe zone padding".  In reference to the
+[demo/host page](../../../../web/testing/gesture-recognizer/), this is
+visualized as the inner, lighter-colored set of dashed lines.
+
+![Reference image for the host page](./host-page-viz.png)
+
+Any input sequence _starting_ within an "unsafe" area - between the lightly-colored dashed
+lines and the emulated device border, may ignore the boundaries of the safe zone -
+but only for borders on the same side(s) as the violated "padded safe zone" border.
+
+To recap:
+- The "safe zone" is designed to facilitate input-sequence cancellation at borders offset from
+  specific values - typically, from a web page's viewport.
+- "Safe zone padding" is used to allow selective cancellation of specific safe zone borders for
+  sequences that start very close to them.
+
+We have generalized the "safe zone" somewhat by allowing versions based on sources aside from
+the available viewport.  This is largely intended to facilitate interactive demos and testing
+such as the page (and corresponding image) referenced above.
+
+## On "roaming bounds"
+
+At times, it is important to allow an ongoing coordinate-based input sequence to be permitted
+extended boundaries before auto-canceling it.  Consider the nature of a "flick" input on
+keyboards.  For keys in the top of the keyboard, it may be necessary to allow the touchpoint
+to extend beyond the top of the main keyboard element before the flick can be properly
+recognized.  For longpresses, it is also possible for the subkey menu may be displayed beyond
+this area - though the subkey menu's handling of the input sequence should probably be
+handled in its own implementation of `GestureRecognizer`.
+
+The option for "Roaming bounds" exists in order to address such conditions.  This is visualized
+in blue in the image seen earlier.