Merge pull request #10886 from keymanapp/chore/beta-b17s1

chore: Merge 17.0.270 beta back to master

HISTORY.md

@@ -28,6 +28,18 @@
 * chore(common): move to 18.0 alpha (#10713)
 * chore: move to 18.0 alpha
 
+## 17.0.269 beta 2024-02-15
+
+* docs(android): Document using gestures on touch, and remove references to Browser (#10686)
+* docs(android/app): Add help page on using the banner (#10691)
+* fix(web): corrects Android over-deletion of selected text, other context diffs involving selected text (#10662)
+* fix(web): disables banner interaction when suggestions are absent (#10695)
+* fix(web): longpress validation by base key, not current location (#10707)
+
+## 17.0.268 beta 2024-02-15
+
+* chore: move to beta
+
 ## 17.0.267 alpha 2024-02-14
 
 * fix(linux): Use temp dir if we can't create cache dir (#10681)

android/help/basic/index.md

@@ -2,14 +2,14 @@
 title: Basic Help
 ---
 
+* [Using the Banner on the Keyboard](using-the-banner)
+
 * [Switching Between Keyboards](switching-between-keyboards)
 
 * [Installing Custom Keyboards/Dictionaries](installing-custom-packages)
 * [Adding Dictionaries](installing-dictionaries)
 
 * [Using the Settings Screen](config/)
 
-* [Using the Keyman Browser](using-keyman-browser)
-
 * [Removing Keyboards](uninstalling-keyboards)
 * [Removing Dictionaries](uninstalling-dictionaries)

android/help/basic/using-the-banner.md

@@ -0,0 +1,27 @@
+---
+title: Using the Banner on the Keyboard - Keyman for Android Help
+---
+
+## About the Keyboard Banner
+
+Keyman keyboards now always display a banner above the keyboard for one of the following functionalities:
+
+* Display suggestions (See "Using the Suggestion Banner" below)
+* Display a Keyman-themed banner so popups and gestures for the top row of keys are visible
+* Reserved for future functionality
+
+## Using the Suggestion Banner
+
+If a [dictionary is installed](installing-dictionaries) and enabled for the active Keyman keyboard, the banner will display suggestions that can be selected.
+
+![](../android_images/settings-suggestions-ap.png)
+
+* Drag the banner horizontally to see more suggestions
+* Overly-long suggestions are partially hidden, but expand when a finger is held on them
+* Banner displays up to 8 suggestions
+
+## The Keyman Themed Banner
+
+When suggestions are disabled or unavailable, the Keyman-themed banner will display instead. This is displayed so popups and gestures for the top row of keys are visible. 
+
+![](../android_images/themed-banner.png)

android/help/context/gestures.md

@@ -0,0 +1,13 @@
+---
+title: Gesture Hints and Tips
+---
+
+## Using Gestures on the Keyboard Keys
+There are now several gestures available to interact with some keys on the keyboard. Keys which have gestures available will normally show them as a hint in the top right of the key:
+
+![](../android_images/touch-hold-ap.png)
+
+* **Long press**: Press and hold a key, and after a moment a submenu will appear. Slide the finger to the submenu to select a key. Release the finger, and the highlighted key from the submenu will be output.
+* **Flick**: Press and hold a key, and then slide the finger in various directions on a key to reach alternate outputs. The key will animate to show the expected output when the finger gets released. A common flick is to slide down to reach numerals on the top row of the keyboard.
+* **Multitap**: Some keys can be pressed repeatedly and rapidly to reach alternate outputs. Tapping rapidly twice on <kbd>Shift</kbd> will activate <kbd>Caps Lock</kbd> on many keyboards.
+

android/help/context/index.md

@@ -2,5 +2,6 @@
 title: Contextual Help
 ---
 
-* [The Keyman Menu (Phone Layout)](menu-phone)
-* [The Keyman Menu (Tablet Layout)](menu-tablet)
+* [The Keyboard Keys and Keyman Menu (Phone Layout)](menu-phone)
+* [The Keyboard Keys and Keyman Menu (Tablet Layout)](menu-tablet)
+* [Gesture Hints and Tips](gestures)

android/help/context/menu-phone.md

@@ -9,14 +9,13 @@ title: Keyman for Android (Phone Layout)
 | ![](../android_images/backspace-ap.png) | Backspace |
 | ![](../android_images/return-ap.png) | Return |
 | ![](../android_images/shift-ap.png) | Shift key. Long press this key to access the <kbd>CTRL</kbd>, <kbd>ALT</kbd> and <kbd>CTRL</kbd><kbd>ALT</kbd> keys (which can access additional key layers) |
-| ![](../android_images/touch-hold-ap.png) | Keys with a small dot in the top right corner indicate a long press key. Access further functionality by long pressing the key |
-| ![](../android_images/share-a.png) | Share your text with other apps like Messages, Gmail, or Twitter. Some versions of Android also let you copy your text to the clipboard. |
+| ![](../android_images/touch-hold-ap.png) | There are several [gestures](gestures) to interact with some keys on the keyboard. Keys which have gestures available will normally show a hint in the top right of the key.<br>Gestures include: long press, flick, and multitap. |
 
 ----
 
 |   | Toolbar Icons |
 |---|---|
-| ![](../android_images/browser-a.png) | Open the Keyman Browser to use the web in your language |
+| ![](../android_images/share-a.png) | Share your text with other apps like Messages, Gmail, or Twitter. Some versions of Android also let you copy your text to the clipboard. |
 | ![](../android_images/menu-icon-a.png) | Open the menu for additional options |
 | ![](../android_images/font-size-a.png) | Adjust the font size |
 | ![](../android_images/delete-a.png) | Delete all current text |

android/help/context/menu-tablet.md

@@ -9,14 +9,13 @@ title: Keyman for Android (Tablet Layout)
 | ![](../android_images/backspace-at.png) | Backspace |
 | ![](../android_images/return-at.png) | Return |
 | ![](../android_images/shift-at.png) | Shift key. Long press this key to access the <kbd>CTRL</kbd>, <kbd>ALT</kbd> and <kbd>CTRL</kbd><kbd>ALT</kbd> keys (which can access additional key layers) |
-| ![](../android_images/touch-hold-at.png) | Keys with a small dot in the top right corner indicate a long press key. Access further functionality by long pressing the key |
+| ![](../android_images/touch-hold-at.png) | There are several [gestures](gestures) to interact with some keys on the keyboard. Keys which have gestures available will normally show a hint in the top right of the key.<br>Gestures include: long press, flick, and multitap. |
 
 ----
 
 |   | Toolbar Icons |
 |---|---|
 | ![](../android_images/share-a.png) | Share your text with other atps like Messages, Gmail, or Twitter. Some versions of Android also let you copy your text to the clipboard. |
-| ![](../android_images/browser-a.png) | Open the Keyman Browser to use the web in your language |
 | ![](../android_images/menu-icon-a.png) | Open the menu for additional options |
 | ![](../android_images/font-size-a.png) | Adjust the font size |
 | ![](../android_images/delete-a.png) | Delete all current text |

android/help/index.md

@@ -12,9 +12,10 @@ title: Keyman for Android 18.0 Help
 * [How To - Download and Install a Keyman Keyboard](start/installing-keyboards)
 * [Enabling Keyman as a System-Wide Keyboard](start/enabling-system-keyboard)
 
-## [Using the Menu](context/)
-* [Using the menu buttons (phone layout)](context/menu-phone)
-* [Using the menu buttons (tablet layout)](context/menu-tablet)
+## [Using the Keyboard Keys and Menu](context/)
+* [Using the keyboard keys and menu buttons (phone layout)](context/menu-phone)
+* [Using the keyboard keys and menu buttons (tablet layout)](context/menu-tablet)
+* [Gesture Hints and Tips](context/gestures)
 
 ## Ask for Help
 * [Ask other users in the SIL Keyman Community](https://community.software.sil.org/c/keyman)
@@ -26,11 +27,11 @@ title: Keyman for Android 18.0 Help
 * [How To - Integrating Keyman for Android](troubleshooting/integrating)
 
 ### [Using Keyman for Android](basic/)
+* [Using the Banner on the Keyboard](basic/using-the-banner)
 * [Switching Between Keyboards](basic/switching-between-keyboards)
 * [Installing Custom Keyboards/Dictionaries](basic/installing-custom-packages)
 * [Adding Dictionaries](basic/installing-dictionaries)
 * [Using the Settings Screen](basic/config/)
-* [Using the Keyman Browser](basic/using-keyman-browser)
 * [Removing Keyboards](basic/uninstalling-keyboards)
 * [Removing Dictionaries](basic/uninstalling-dictionaries)
 

android/help/start/enabling-system-keyboard.md

@@ -5,7 +5,7 @@ title: How To - Enabling Keyman as a System-Wide Keyboard
 ## Enabling System Wide Keyboards
 Step 1)
 Open the Keyman app and select the menu for additional options.
-The screenshots below are of a device running Android 9.0 Pie.
+The screenshots below are of a device running Android 12 Snow Cone.
 
 ![](../android_images/settings1-ap.png)
 

common/web/keyboard-processor/src/index.ts

@@ -39,6 +39,7 @@ export { default as KeyMapping } from "./text/keyMapping.js";
 export { default as OutputTarget } from "./text/outputTarget.js";
 export * from "./text/outputTarget.js";
 export { default as RuleBehavior } from "./text/ruleBehavior.js";
+export * from "./text/stringDivergence.js";
 export * from "./text/systemStores.js";
 
 export * from "@keymanapp/web-utils";

common/web/keyboard-processor/src/text/outputTarget.ts

@@ -1,6 +1,7 @@
 ///<reference types="@keymanapp/models-types" />
 
 import { extendString } from "@keymanapp/web-utils";
+import { findCommonSubstringEndIndex } from "./stringDivergence.js";
 
 extendString();
 
@@ -120,85 +121,24 @@ export default abstract class OutputTarget {
    * @param from An output target (preferably a Mock) representing the prior state of the input/output system.
    */
   buildTransformFrom(original: OutputTarget): Transform {
-    let to = this.getText();
-    let from = original.getText();
+    const toLeft = this.getTextBeforeCaret();
+    const fromLeft = original.getTextBeforeCaret();
 
-    let fromCaret = original.getDeadkeyCaret();
-    let toCaret = this.getDeadkeyCaret();
+    const leftDivergenceIndex = findCommonSubstringEndIndex(fromLeft, toLeft, false);
+    const deletedLeft = fromLeft.substring(leftDivergenceIndex)._kmwLength();
+    // No need for our specialized variant here.
+    const insertedText = toLeft.substring(leftDivergenceIndex);
 
-    // Step 1:  Determine the number of left-deletions.
-    let maxSMPLeftMatch = fromCaret < toCaret ? fromCaret : toCaret;
+    const toRight = this.getTextAfterCaret();
+    const fromRight = original.getTextAfterCaret();
+    const rightDivergenceIndex = findCommonSubstringEndIndex(fromRight, toRight, true);
 
-    // We need the corresponding non-SMP caret location in order to binary-search efficiently.
-    // (Examining code units is much more computationally efficient.)
-    let maxLeftMatch = to._kmwCodePointToCodeUnit(maxSMPLeftMatch);
+    // Right insertions aren't supported, but right deletions will matter in some scenarios.
+    // In particular, once we allow right-deletion for pred-text suggestions applied with the
+    // caret mid-word..
+    const deletedRight = fromRight.substring(0, rightDivergenceIndex + 1)._kmwLength();
 
-    // 1.1:  use a non-SMP-aware binary search to determine the divergence point.
-    let start = 0;
-    let end = maxLeftMatch;  // the index AFTER the last possible matching char.
-
-    // This search is O(maxLeftMatch).  1/2 + 1/4 + 1/8 + ... converges to = 1.
-    while(start < end) {
-      let mid = Math.floor((end+start+1) / 2); // round up (compare more)
-      let fromLeft = from.substr(start, mid-start);
-      let toLeft   = to.substr(start, mid-start);
-
-      if(fromLeft == toLeft) {
-        start = mid;
-      } else {
-        end = mid - 1;
-      }
-    }
-
-    // At the loop's end:  `end` now holds the non-SMP-aware divergence point.
-    // The 'caret' is after the last matching code unit.
-
-    // 1.2:  detect a possible surrogate-pair split scenario, correcting for it
-    //       (by moving the split before the high-surrogate) if detected.
-
-    // If the split location is precisely on either end of the context, we can't
-    // have split a surrogate pair.
-    if(end > 0 && end < maxLeftMatch) {
-      let potentialHigh    = from.charCodeAt(end-1);
-      let potentialFromLow = from.charCodeAt(end);
-      let potentialToLow   = to.charCodeAt(end);
-
-      // if potentialHigh is a possible high surrogate...
-      if(potentialHigh >= 0xD800 && potentialHigh <= 0xDBFF) {
-        // and at least one potential 'low' is a possible low surrogate...
-        let flag = potentialFromLow >= 0xDC00 && potentialFromLow <= 0xDFFF;
-        flag = flag || (potentialToLow >= 0XDC00 && potentialToLow <= 0xDFFF);
-
-        // Correct the split location, moving it 'before' the high surrogate.
-        if(flag) {
-          end = end - 1;
-        }
-      }
-    }
-
-    // 1.3:  take substring from start to the split point; determine SMP-aware length.
-    //       This yields the SMP-aware divergence index, which gives the number of left-deletes.
-    let newCaret = from._kmwCodeUnitToCodePoint(end);
-    let deletedLeft = fromCaret - newCaret;
-
-    // Step 2:  Determine the other properties.
-    // Since the 'after' OutputTarget's caret indicates the end of any inserted text, we
-    // can easily calculate the rest.
-    let insertedLength = toCaret - newCaret;
-    let delta = to._kmwSubstr(newCaret, insertedLength);
-
-    let undeletedRight = to._kmwLength() - toCaret;
-    let originalRight = from._kmwLength() - fromCaret;
-    let deletedRight = originalRight - undeletedRight;
-
-    // May occur when reverting a suggestion that had been applied mid-word.
-    if(deletedRight < 0) {
-      // Restores deleteRight characters.
-      delta = delta + to._kmwSubstr(toCaret, -deletedRight);
-      deletedRight = 0;
-    }
-
-    return new TextTransform(delta, deletedLeft, deletedRight);
+    return new TextTransform(insertedText, deletedLeft, deletedRight);
   }
 
   buildTranscriptionFrom(original: OutputTarget, keyEvent: KeyEvent, readonly: boolean, alternates?: Alternate[]): Transcription {
@@ -214,6 +154,13 @@ export default abstract class OutputTarget {
    * @param original An `OutputTarget` (usually a `Mock`).
    */
   restoreTo(original: OutputTarget) {
+    this.clearSelection();
+    // We currently do not restore selected text; the mechanism isn't supported at present for
+    // all output target types - especially in regard to re-selecting the text if restored.
+    //
+    // I believe this would mostly matter if/when reverting predictions based upon selected text.
+    // That pattern isn't well-supported yet, though.
+
     //
     this.setTextBeforeCaret(original.getTextBeforeCaret());
     this.setTextAfterCaret(original.getTextAfterCaret());
@@ -223,6 +170,10 @@ export default abstract class OutputTarget {
   }
 
   apply(transform: Transform) {
+    // Selected text should disappear on any text edit; application of a transform
+    // certainly qualifies.
+    this.clearSelection();
+
     if(transform.deleteRight) {
       this.setTextAfterCaret(this.getTextAfterCaret()._kmwSubstr(transform.deleteRight));
     }