feat(web): gesture stage sequencing 🐵

[jahorton]

AKA coordinating & correlating the sequence of related gesture components over time.

This PR does a few things:

1. There have been a few shifts to the gesture-model spec format and to the resolution-handling spec format.

   These changes have arisen out of observations that occurred at the newly-achieved level of integration.

   1. I originally made the distinction between 'chain' and 'optional-chain' before I'd fully thought through how multiple gesture-sources would operate together. Given how gesture-selection operates, it is quite possible to process two different gesture sequences in parallel, neither blocking the other. As 'chain' was originally envisioned to 'block' while 'optional-chain' was not, there's little significant distinction now.
   2. For special rejection handling, 'replace' takes the place of 'optional-chain'. It pretty much maintains the original behavior but is exclusive to cases where a gesture-model has been rejected and desires some form of a reset due to change in the GestureSource's condition.
   3. There's a new flag for gesture-model contacts currently labeled 'resetOnResolve'. Its purpose: any GestureSource matching the corresponding component is not considered part of the resolving gesture model; it's just a 'trigger' and should be treated as part of an independent gesture. This cleans up the interface and/or reporting of shortcutting simple taps, which was a pain point I'd been noting... and this was also the perfect workaround for the one complication that arose when merging 'chain' and 'optional-chain' resolution types.
      • The "short version" of the "pain point": previously, if one simple tap "shortcut" another one, they would be treated as part of the "same gesture" by the engine - just "separate stages" of the same gesture sequence. Now, they can be kept separate, which matches one's natural expectation for the case.
   4. While not yet vetted, sustainWhenNested is designed to facilitate a complication that will arise for longpresses that are triggered during a modipress interaction: if the subkey menu is shown when the modipress ends, we should probably 'sustain' the subkey selection mode instead of immediately returning to the original layer. This would be a 'nested' longpress... hence the flag name.

2. This adds a formal spec for defining the gestures and gesture sets that are to be utilized by the gesture engine - see GestureModelDefs.

   • It's nothing complex: just "array of gesture models" and "array of named model-id arrays", the latter of which defines a "gesture set". default is a required "gesture set" entry.

3. The main class corresponding to the new layer is called GestureSequence, as it exists to track the individual gesture components (models) comprising the ongoing 'gesture sequence' over time and facilitate event handling based on the sequence's development as new components are recognized.

   1. Upon creation, the class will generate a 'stage' event for its first stage after the smallest-possible async delay, allowing it to be handled in the same manner as all subsequent stages, despite it being required for the object's construction.
      • The event's parameter will be of the GestureStageReport type, which makes the critical data available to external modules while minimally exposing things that are only relevant internally.
   2. When the ongoing gesture sequence is guaranteed to be 100% complete, it will raise a 'complete' event to signal this.
   3. The object is both the external-friendly potential-API object useful for tracking gestures and the engine that properly handles transition between each stage of the gesture as it develops over time.

4. Finally, what's a good PR like this without a lot of nice, new automated tests to help support and maintain it?

   • To be clear, and alleviate PR size concerns: the tests themselves are currently responsible for about 700 of the PR's new lines.
   • These tests helped motivate many of the fixes found in fix(web): early cherrypick of bugfixes in gesture-staging dependencies, minor cleanup 🐵 #9599.
   • Tests currently cover simple-tap, multitap, longpress, and subkey-select states. There's no flick or modipress coverage yet.

@keymanapp-test-bot skip

[keymanapp-test-bot]

User Test Results

Test specification and instructions

User tests are not required

Test Artifacts

• Android
  • Keyman for Android apk
  • FirstVoices for Android 16.0 apk
  • FirstVoices Keyboards for Android apk
  • KeyboardHarness apk
  • Keyman for Android 16.0 apk
  • KMSample1 apk
  • KMSample2 apk
• Developer
  • Keyman Developer
  • Compiler Regression Tests
  • kmcomp.zip
• iOS
  • Keyman for iOS (simulator image)
  • FirstVoices Keyboards for iOS (simulator image)
  • TestFlight internal PR build version - 17.0.181 (0.9455.9255)
• Keyboards
  • Test Keyboards
• Web
  • KeymanWeb Test Home
• Windows
  • Keyman for Windows
  • FirstVoices Keyboards for Windows
  • Text Editor (32 bit)
  • Text Editor (64 bit)

[mcdurdin]

LGTM