refactor(web): move RuleBehavior to engine/keyboard

This requires to move some other files around. Also move `finalize`
and `mergeInDefaults` methods to processor and rename them to
`finalizeProcessorAction` and `mergeInOtherProcessorAction` (decided
to directly use the term `ProcessorAction`, to which `RuleBehavior`
will be renamed to in a following PR).

Co-authored-by: Marc Durdin <[email protected]>

Author: ermshiperete

web/src/app/browser/src/configuration.ts

@@ -1,8 +1,8 @@
 import { EngineConfiguration, InitOptionSpec, InitOptionDefaults } from "keyman/engine/main";
 
 import { OutputTargetElementWrapper as DOMOutputTarget } from 'keyman/engine/element-wrappers';
-import { OutputTargetInterface } from 'keyman/engine/keyboard';
-import { isEmptyTransform, RuleBehavior } from 'keyman/engine/js-processor';
+import { OutputTargetInterface, RuleBehavior } from 'keyman/engine/keyboard';
+import { isEmptyTransform } from 'keyman/engine/js-processor';
 import { AlertHost } from "./utils/alertHost.js";
 import { whenDocumentReady } from "./utils/documentReady.js";
 

web/src/app/webview/src/contextManager.ts

@@ -1,6 +1,6 @@
-import { JSKeyboard, Keyboard, OutputTargetInterface } from 'keyman/engine/keyboard';
+import { JSKeyboard, Keyboard, OutputTargetInterface, Transcription, TextTransform } from 'keyman/engine/keyboard';
 // TODO-web-core: remove usage of OutputTargetBase, use OutputTargetInterface instead
-import { Mock, Transcription, findCommonSubstringEndIndex, isEmptyTransform, TextTransform, OutputTargetBase } from 'keyman/engine/js-processor';
+import { Mock, findCommonSubstringEndIndex, isEmptyTransform, OutputTargetBase } from 'keyman/engine/js-processor';
 import { KeyboardStub } from 'keyman/engine/keyboard-storage';
 import { ContextManagerBase } from 'keyman/engine/main';
 import { WebviewConfiguration } from './configuration.js';
@@ -31,7 +31,8 @@ export class ContextHost extends Mock {
       let transform: TextTransform = null;
 
       if(transcription) {
-        const preInput = transcription.preInput;
+        //TODO-web-core: shouldn't need cast in the future?
+        const preInput = transcription.preInput as Mock;
         // If our saved state matches the `preInput` from the incoming transcription, just reuse its transform.
         // Will generally not match during multitap operations, though.
         //

web/src/app/webview/src/keymanEngine.ts

@@ -1,5 +1,4 @@
-import { DeviceSpec, DefaultRules } from 'keyman/engine/keyboard';
-import { RuleBehavior } from 'keyman/engine/js-processor';
+import { DeviceSpec, DefaultRules, RuleBehavior } from 'keyman/engine/keyboard';
 import { KeymanEngineBase, KeyboardInterfaceBase } from 'keyman/engine/main';
 import { AnchoredOSKView, ViewConfiguration, StaticActivator } from 'keyman/engine/osk';
 import { getAbsoluteX, getAbsoluteY } from 'keyman/engine/dom-utils';

web/src/engine/js-processor/src/index.ts

@@ -1,8 +1,7 @@
 export { BeepHandler, JSKeyboardProcessor, LogMessageHandler, ProcessorInitOptions } from "./jsKeyboardProcessor.js";
-export { RuleBehavior } from "./ruleBehavior.js";
 export { JSKeyboardInterface, KeyInformation, StoreNonCharEntry } from "./jsKeyboardInterface.js";
 export * from "./deadkeys.js";
-export * from "./stores.js";
+export { type ComplexKeyboardStore } from "./stores.js";
 export { OutputTargetBase } from "./outputTargetBase.js";
 export * from "./outputTargetBase.js";
 export { Mock } from "./mock.js";

web/src/engine/js-processor/src/jsKeyboardInterface.ts

@@ -7,14 +7,27 @@
 
 import { type DeviceSpec, KMWString } from "@keymanapp/web-utils";
 import { ModifierKeyConstants } from '@keymanapp/common-types';
-import { Codes, type KeyEvent, KeyMapping, JSKeyboard, KeyboardHarness, KeyboardKeymanGlobal, type OutputTargetInterface, VariableStoreDictionary } from "keyman/engine/keyboard";
+import {
+  Codes,
+  JSKeyboard,
+  KeyboardHarness,
+  KeyboardKeymanGlobal,
+  KeyMapping,
+  MutableSystemStore,
+  SystemStore,
+  SystemStoreIDs,
+  type KeyEvent,
+  type OutputTargetInterface,
+  RuleBehavior,
+  VariableStore,
+  VariableStoreDictionary,
+  VariableStoreSerializer,
+} from "keyman/engine/keyboard";
 import { type OutputTargetBase }  from './outputTargetBase.js';
 import { type Deadkey } from './deadkeys.js';
 import { Mock } from "./mock.js";
-import { RuleBehavior }  from "./ruleBehavior.js";
-import { SystemStoreIDs, SystemStore, MutableSystemStore } from "keyman/engine/keyboard";
 import { PlatformSystemStore } from './platformSystemStore.js';
-import { ComplexKeyboardStore, type KeyboardStore, KeyboardStoreElement, VariableStore, VariableStoreSerializer } from "./stores.js";
+import { ComplexKeyboardStore, type KeyboardStore, KeyboardStoreElement } from "./stores.js";
 
 //#endregion
 

web/src/engine/js-processor/src/jsKeyboardProcessor.ts

@@ -10,20 +10,19 @@ import { EventEmitter } from 'eventemitter3';
 import { ModifierKeyConstants } from '@keymanapp/common-types';
 import {
   Codes, type JSKeyboard, MinimalKeymanGlobal, KeyEvent, Layouts,
-  DefaultRules, EmulationKeystrokes,
-  type MutableSystemStore, SystemStoreIDs,
+  DefaultRules, EmulationKeystrokes, type MutableSystemStore,
+  OutputTargetInterface, RuleBehavior, SystemStoreIDs
 } from "keyman/engine/keyboard";
 import { Mock } from "./mock.js";
 import { type OutputTargetBase }  from "./outputTargetBase.js";
-import { RuleBehavior }  from "./ruleBehavior.js";
 import { JSKeyboardInterface }  from './jsKeyboardInterface.js';
 import { DeviceSpec, globalObject, KMWString } from "@keymanapp/web-utils";
 
 // #endregion
 
 // Also relies on @keymanapp/web-utils, which is included via tsconfig.json.
 
-export type BeepHandler = (outputTarget: OutputTargetBase) => void;
+export type BeepHandler = (outputTarget: OutputTargetInterface) => void;
 export type LogMessageHandler = (str: string) => void;
 
 export interface ProcessorInitOptions {
@@ -250,7 +249,7 @@ export class JSKeyboardProcessor extends EventEmitter<EventMap> {
         if(!matchBehavior) {
           matchBehavior = defaultBehavior;
         } else {
-          matchBehavior.mergeInDefaults(defaultBehavior);
+          this.mergeInOtherProcessorAction(matchBehavior, defaultBehavior);
         }
         matchBehavior.triggerKeyDefault = false; // We've triggered it successfully.
       } // If null, we must rely on something else (like the browser, in DOM-aware code) to fulfill the default.
@@ -577,8 +576,8 @@ export class JSKeyboardProcessor extends EventEmitter<EventMap> {
   private performNewContextEvent(outputTarget: OutputTargetBase): RuleBehavior {
     const ruleBehavior = this.processNewContextEvent(this.contextDevice, outputTarget);
 
-    if(ruleBehavior) {
-      ruleBehavior.finalize(this, outputTarget, true);
+    if (ruleBehavior) {
+      this.finalizeProcessorAction(ruleBehavior, outputTarget);
     }
     return ruleBehavior;
   }
@@ -610,4 +609,76 @@ export class JSKeyboardProcessor extends EventEmitter<EventMap> {
       }
     }
   };
+
+  public finalizeProcessorAction(data: RuleBehavior, outputTarget: OutputTargetInterface): void {
+    if (!data.transcription) {
+      throw "Cannot finalize a RuleBehavior with no transcription.";
+    }
+
+    if (this.beepHandler && data.beep) {
+      this.beepHandler(outputTarget);
+    }
+
+    for (const storeID in data.setStore) {
+      const sysStore = this.keyboardInterface.systemStores[storeID];
+      if (sysStore) {
+        try {
+          sysStore.set(data.setStore[storeID]);
+        } catch (error) {
+          if (this.errorLogger) {
+            this.errorLogger("Rule attempted to perform illegal operation - 'platform' may not be changed.");
+          }
+        }
+      } else if (this.warningLogger) {
+        this.warningLogger("Unknown store affected by keyboard rule: " + storeID);
+      }
+    }
+
+    this.keyboardInterface.applyVariableStores(data.variableStores);
+
+    if (this.keyboardInterface.variableStoreSerializer) {
+      for (const storeID in data.saveStore) {
+        this.keyboardInterface.variableStoreSerializer.saveStore(this.activeKeyboard.id, storeID, data.saveStore[storeID]);
+      }
+    }
+
+    if (data.triggersDefaultCommand) {
+      const keyEvent = data.transcription.keystroke;
+      this.defaultRules.applyCommand(keyEvent, outputTarget);
+    }
+
+    if (this.warningLogger && data.warningLog) {
+      this.warningLogger(data.warningLog);
+    } else if (this.errorLogger && data.errorLog) {
+      this.errorLogger(data.errorLog);
+    }
+  }
+
+  /**
+   * Merges default-related behaviors from another RuleBehavior into this one.  Assumes that the current instance
+   * "came first" chronologically.  Both RuleBehaviors must be sourced from the same keystroke.
+   *
+   * Intended use:  merging rule-based behavior with default key behavior during scenarios like those described
+   * at https://github.com/keymanapp/keyman/pull/4350#issuecomment-768753852.
+   *
+   * This function does not attempt a "complete" merge for two fully-constructed RuleBehaviors!  Things
+   * WILL break for unintended uses.
+   * @param other
+   */
+  private mergeInOtherProcessorAction(first: RuleBehavior, other: RuleBehavior): void {
+    const keystroke = first.transcription.keystroke;
+    const keyFromOther = other.transcription.keystroke;
+    if (keystroke.Lcode != keyFromOther.Lcode || keystroke.Lmodifiers != keyFromOther.Lmodifiers) {
+      throw "RuleBehavior default-merge not supported unless keystrokes are identical!";
+    }
+
+    first.triggersDefaultCommand = first.triggersDefaultCommand || other.triggersDefaultCommand;
+
+    const mergingMock = Mock.from(first.transcription.preInput, false);
+    mergingMock.apply(first.transcription.transform);
+    mergingMock.apply(other.transcription.transform);
+
+    first.transcription = mergingMock.buildTranscriptionFrom(first.transcription.preInput, keystroke, false, first.transcription.alternates);
+  }
+
 }

web/src/engine/js-processor/src/mock.ts

@@ -1,3 +1,4 @@
+import { OutputTargetInterface } from 'keyman/engine/keyboard';
 import { OutputTargetBase } from './outputTargetBase.js';
 import { KMWString } from '@keymanapp/web-utils';
 
@@ -25,10 +26,18 @@ export class Mock extends OutputTargetBase {
     this.selForward = this.selEnd >= this.selStart;
   }
 
+  static assertIsOutputTargetBase(outputTarget: OutputTargetInterface): asserts outputTarget is OutputTargetBase {
+    if (!(outputTarget instanceof OutputTargetBase)) {
+      throw new TypeError("outputTarget is not a OutputTargetBase");
+    }
+  }
+
   // Clones the state of an existing EditableElement, creating a Mock version of its state.
-  static from(outputTarget: OutputTargetBase, readonly?: boolean) {
+  static from(outputTarget: OutputTargetInterface, readonly?: boolean): Mock {
     let clone: Mock;
 
+    this.assertIsOutputTargetBase(outputTarget);
+
     if (outputTarget instanceof Mock) {
       // Avoids the need to run expensive kmwstring.ts `length()`
       // calculations when deep-copying Mock instances.
@@ -56,7 +65,7 @@ export class Mock extends OutputTargetBase {
     }
 
     // Also duplicate deadkey state!  (Needed for fat-finger ops.)
-    clone.setDeadkeys(outputTarget.deadkeys());
+    clone.setDeadkeys((outputTarget as OutputTargetBase).deadkeys());
 
     return clone;
   }

web/src/engine/js-processor/src/outputTargetBase.ts

@@ -1,7 +1,7 @@
 import { KMWString } from "@keymanapp/web-utils";
+import { Alternate, OutputTargetInterface, TextTransform, Transcription } from 'keyman/engine/keyboard';
 import { findCommonSubstringEndIndex } from "./stringDivergence.js";
 import { Mock } from "./mock.js";
-import { OutputTargetInterface } from 'keyman/engine/keyboard';
 
 // Defines deadkey management in a manner attachable to each element interface.
 import { type KeyEvent } from 'keyman/engine/keyboard';
@@ -17,53 +17,6 @@ export function isEmptyTransform(transform: LexicalModelTypes.Transform) {
   return transform.insert === '' && transform.deleteLeft === 0 && (transform.deleteRight ?? 0) === 0;
 }
 
-export class TextTransform implements LexicalModelTypes.Transform {
-  readonly insert: string;
-  readonly deleteLeft: number;
-  readonly deleteRight: number;
-  readonly erasedSelection: boolean;
-  id: number;
-
-  constructor(insert: string, deleteLeft: number, deleteRight: number, erasedSelection: boolean) {
-    this.insert = insert;
-    this.deleteLeft = deleteLeft;
-    this.deleteRight = deleteRight;
-    this.erasedSelection = erasedSelection;
-  }
-
-  public static readonly nil = new TextTransform('', 0, 0, false);
-}
-
-export class Transcription {
-  readonly token: number;
-  readonly keystroke: KeyEvent;
-  readonly transform: TextTransform;
-  alternates: Alternate[]; // constructed after the rest of the transcription.
-  readonly preInput: Mock;
-
-  private static tokenSeed: number = 0;
-
-  constructor(keystroke: KeyEvent, transform: TextTransform, preInput: Mock, alternates?: Alternate[]/*, removedDks: Deadkey[], insertedDks: Deadkey[]*/) {
-    const token = this.token = Transcription.tokenSeed++;
-
-    this.keystroke = keystroke;
-    this.transform = transform;
-    this.alternates = alternates;
-    this.preInput = preInput;
-
-    this.transform.id = this.token;
-
-    // Assign the ID to each alternate, as well.
-    if(alternates) {
-      alternates.forEach(function(alt) {
-        alt.sample.id = token;
-      });
-    }
-  }
-}
-
-export type Alternate = LexicalModelTypes.ProbabilityMass<LexicalModelTypes.Transform>;
-
 export abstract class OutputTargetBase implements OutputTargetInterface {
   private _dks: DeadkeyTracker;
 
@@ -122,7 +75,7 @@ export abstract class OutputTargetBase implements OutputTargetInterface {
    * As such, it assumes that the caret is immediately after any inserted text.
    * @param from An output target (preferably a Mock) representing the prior state of the input/output system.
    */
-  buildTransformFrom(original: OutputTargetBase): TextTransform {
+  buildTransformFrom(original: OutputTargetInterface): TextTransform {
     const toLeft = this.getTextBeforeCaret();
     const fromLeft = original.getTextBeforeCaret();
 
@@ -143,7 +96,7 @@ export abstract class OutputTargetBase implements OutputTargetInterface {
     return new TextTransform(insertedText, deletedLeft, deletedRight, original.getSelectedText() && !this.getSelectedText());
   }
 
-  buildTranscriptionFrom(original: OutputTargetBase, keyEvent: KeyEvent, readonly: boolean, alternates?: Alternate[]): Transcription {
+  buildTranscriptionFrom(original: OutputTargetInterface, keyEvent: KeyEvent, readonly: boolean, alternates?: Alternate[]): Transcription {
     const transform = this.buildTransformFrom(original);
 
     // If we ever decide to re-add deadkey tracking, this is the place for it.