fix(web): define IME interfaces in KeyboardInterfaceBase

Ensure that the IME interface methods are all defined for both browser
and webview modes. Deprecate 'Element' methods and replace with
'TextStore' to clarify return type. Add deprecation flags where needed
and update documentation accordingly.

Fixes: #16144

web/docs/engine/reference/compatibility/FocusLastActiveElement.md

@@ -1,26 +0,0 @@
----
-title: FocusLastActiveElement
----
-  
-## Summary
-
-Restore the focus to the element active before input was moved to
-KeymanWeb.
-
-## Syntax
-
-```
-keyman.FocusLastActiveElement()
-```
-
-### Parameters
-
-None.
-
-### Return Value
-
-`undefined`
-
-### Replaced By
-
-[`keyman.focusLastActiveElement()`](../core/focusLastActiveElement)

web/docs/engine/reference/compatibility/GetLastActiveElement.md

@@ -1,26 +0,0 @@
----
-title: GetLastActiveElement
----
-  
-## Summary
-
-Returns the last active target element before the current KMW operation.
-
-## Syntax
-
-```
-keyman.GetLastActiveElement();
-```
-
-### Parameters
-
-None.
-
-### Return Value
-
-`Element`
-:   The requested element.
-
-### Replaced By
-
-[`keyman.getLastActiveElement()`](../core/getLastActiveElement)

web/docs/engine/reference/compatibility/HideHelp.md

@@ -1,25 +0,0 @@
----
-title: HideHelp
----
-  
-## Summary
-
-Hides the OSK (visual help).
-
-## Syntax
-
-```
-keyman.HideHelp();
-```
-
-### Parameters
-
-None.
-
-### Return Value
-
-`undefined`
-
-### Replaced By
-
-[`keyman.osk.hide()`](../osk/hide)

web/docs/engine/reference/compatibility/ShowPinnedHelp.md

@@ -1,26 +0,0 @@
----
-title: ShowPinnedHelp
----
-  
-## Summary
-
-Shows the on-screen keyboard and locks it at the resulting location.
-
-## Syntax
-
-```
-keyman.ShowPinnedHelp(x, y);
-```
-
-### Parameters
-
-None.
-
-### Return Value
-
-`undefined`
-
-### Replaced by
-
-[`keyman.osk.setRect()`](../osk/setRect),
-[`keyman.osk.show()`](../osk/show)

web/docs/engine/reference/compatibility/index.md

@@ -1,33 +0,0 @@
----
-title: Compatibility Functions
----
-  
-The following <span class="emphasis">*KeymanWeb*</span> core functions
-have been retained for compatibility with existing custom keyboards, but
-should not be used in any new keyboards or user interfaces. Equivalent
-new function calls are indicated.
-
-[`GetLastActiveElement` Function](GetLastActiveElement)
-:   [`keyman.getLastActiveElement()`](../core/getLastActiveElement)
-
-<!-- -->
-
-[`FocusLastActiveElement` Function](FocusLastActiveElement)
-:   [`keyman.focusLastActiveElement()`](../core/focusLastActiveElement)
-
-<!-- -->
-
-[`HideHelp` Function](HideHelp)
-:   [`keyman.osk.hide()`](../osk/hide)
-
-<!-- -->
-
-[`ShowHelp` Function](ShowHelp)
-:   [`keyman.osk.setPos()`](../osk/setPos),
-    [`keyman.osk.show()`](../osk/show)
-
-<!-- -->
-
-[`ShowPinnedHelp` Function](ShowPinnedHelp)
-:   [`keyman.osk.setRect()`](../osk/setRect),
-    [`keyman.osk.show()`](../osk/show)

web/docs/engine/reference/index.md

@@ -17,9 +17,6 @@ title: KeymanWeb Reference
 [KeymanWeb Output Functions](interface)
 :   KeymanWeb exposes its keyboard interface object through `window.keyman.interface`, providing a number of functions for low-level processing of input, context and output.
 
-[KeymanWeb Compatibility Functions](compatibility)
-:   The following KeymanWeb core functions have been retained for compatibility with existing custom keyboards, but should not be used in any new keyboards or user interfaces. Equivalent new function calls are indicated.
-
 [Desktop User Interfaces](ui)
 :   Four different KeymanWeb user interfaces for desktop browsers are included, allowing users to select and enable keyboard mapping from a list of installed keyboards, and to control the visibility of the On-Screen Keyboard.
 

web/docs/engine/reference/interface/FocusLastActiveElement.md

@@ -0,0 +1,38 @@
+---
+title: FocusLastActiveElement (deprecated)
+---
+
+## Summary
+
+Restore the focus to the text store active before input was moved to KeymanWeb.
+
+Note that the name is misleading: this function move focus to the last active
+`TextStore`, not the last active `HTMLElement` (in practice, this is equivalent
+in a web browser context).
+
+## Syntax
+
+```js
+keyman.interface.FocusLastActiveElement();
+keyman.interface.focusLastActiveElement();
+KeymanWeb.FocusLastActiveElement();
+KeymanWeb.focusLastActiveElement();
+```
+
+### Parameters
+
+None.
+
+### Return Value
+
+`undefined`
+
+### Replaced By
+
+This function is deprecated; see instead:
+
+* [`keyman.interface.focusLastActiveTextStore()`](focusLastActiveTextStore)
+
+### See also
+
+* [`keyman.focusLastActiveElement()`](../core/focusLastActiveElement)

web/docs/engine/reference/interface/GetLastActiveElement.md

@@ -0,0 +1,39 @@
+---
+title: GetLastActiveElement (deprecated)
+---
+
+## Summary
+
+Returns the last active target text store before the current KMW operation.
+
+Note that the name is misleading: this function returns the last active
+`TextStore`, not the last active `HTMLElement`. Use instead
+[`keyman.interface.getLastActiveTextStore()`](getLastActiveTextStore).
+
+## Syntax
+
+```js
+keyman.interface.GetLastActiveElement();
+keyman.interface.getLastActiveElement();
+KeymanWeb.GetLastActiveElement();
+KeymanWeb.getLastActiveElement();
+```
+
+### Parameters
+
+None.
+
+### Return Value
+
+`TextStore`
+:   The requested text store.
+
+### Replaced By
+
+This function is deprecated; see instead:
+
+* [`keyman.interface.getLastActiveTextStore()`](getLastActiveTextStore)
+
+### See also
+
+* [`keyman.getLastActiveElement()`](../core/getLastActiveElement)

web/docs/engine/reference/interface/HideHelp.md

@@ -0,0 +1,30 @@
+---
+title: HideHelp (deprecated)
+---
+
+## Summary
+
+Hides the OSK (visual help).
+
+## Syntax
+
+```js
+keyman.interface.HideHelp();
+keyman.interface.hideHelp();
+KeymanWeb.HideHelp();
+KeymanWeb.hideHelp();
+```
+
+### Parameters
+
+None.
+
+### Return Value
+
+`undefined`
+
+### Replaced By
+
+This function is deprecated; see instead:
+
+[`keyman.osk.hide()`](../osk/hide)

web/docs/engine/reference/interface/ShowHelp.md

@@ -1,15 +1,18 @@
 ---
-title: ShowHelp
+title: ShowHelp (deprecated)
 ---
-  
+
 ## Summary
 
 Shows the on-screen keyboard at the requested (x, y) coordinates.
 
 ## Syntax
 
-```
-keyman.ShowHelp(x, y);
+```js
+keyman.interface.ShowHelp(x, y);
+keyman.interface.showHelp(x, y);
+KeymanWeb.ShowHelp(x, y);
+KeymanWeb.showHelp(x, y);
 ```
 
 ### Parameters
@@ -28,5 +31,7 @@ keyman.ShowHelp(x, y);
 
 ### Replaced by
 
+This function is deprecated; see instead:
+
 [`keyman.osk.setPos()`](../osk/setPos),
 [`keyman.osk.show()`](../osk/show)

web/docs/engine/reference/interface/ShowPinnedHelp.md

@@ -0,0 +1,31 @@
+---
+title: ShowPinnedHelp (deprecated)
+---
+
+## Summary
+
+Shows the on-screen keyboard and locks it at the resulting location.
+
+## Syntax
+
+```js
+keyman.interface.ShowPinnedHelp(x, y);
+keyman.interface.showPinnedHelp(x, y);
+KeymanWeb.ShowPinnedHelp(x, y);
+KeymanWeb.showPinnedHelp(x, y);
+```
+
+### Parameters
+
+None.
+
+### Return Value
+
+`undefined`
+
+### Replaced by
+
+This function is deprecated; see instead:
+
+* [`keyman.osk.setRect()`](../osk/setRect),
+* [`keyman.osk.show()`](../osk/show)

web/docs/engine/reference/interface/focusLastActiveTextStore.md

@@ -0,0 +1,24 @@
+---
+title: focusLastActiveTextStore
+---
+
+## Summary
+
+Set focus to the currently-focused or most recently focused text store. This is
+for use, for example, by IME keyboards to return the focus to the text store
+after the user clicks on an IME element, without resetting context.
+
+## Syntax
+
+```js
+keyman.interface.focusLastActiveTextStore();
+KeymanWeb.focusLastActiveTextStore();
+```
+
+### Parameters
+
+None.
+
+### Return Value
+
+`undefined`

web/docs/engine/reference/interface/getLastActiveTextStore.md

@@ -0,0 +1,26 @@
+---
+title: getLastActiveTextStore
+---
+
+## Summary
+
+Get the currently or most recently focused text store. This is for use by IME
+keyboards, to allow for more complex focus interactions when clicking IME
+elements.
+
+## Syntax
+
+```js
+keyman.interface.getLastActiveTextStore();
+KeymanWeb.getLastActiveTextStore();
+```
+
+### Parameters
+
+None.
+
+### Return Value
+
+`TextStore`
+:   The last active text store.
+

web/docs/engine/reference/interface/index.md

@@ -42,10 +42,16 @@ Custom user interfaces would not normally use these functions, but they are desc
 :   Context deletion - removes the specified number of deadkeys and characters from the left of the caret.
 :   Shorthand name: `KeymanWeb.KDC`
 
+[`focusLastActiveTextStore` Function](focusLastActiveTextStore)
+:  Set focus to the currently-focused or most recently focused text store.
+
 [`fullContextMatch` Function](fullContextMatch)
 :   Context matching: Returns `true` if the current context matches the specified rule context specification.
 :   Shorthand name: `KeymanWeb.KFCM`
 
+[`getLastActiveTextStore` Function](getLastActiveTextStore)
+:  Get the currently or most recently focused text store. This is for use by IME keyboards.
+
 [`ifStore` Function](ifStore)
 :   `ifStore` compares the content of a [system `store`](/developer/language/guide/stores#toc-system-stores) with a string value.
 :   Shorthand name: `KeymanWeb.KIFS`
@@ -105,3 +111,25 @@ Custom user interfaces would not normally use these functions, but they are desc
 [`stateMatch` Function](stateMatch)
 :   State-key matching: Returns `true` if the event matches the rule's state-key requirements.
 :   Shorthand name: `KeymanWeb.KSM`
+
+## Deprecated functions for IMEs
+
+The following functions have been retained for compatibility with existing IME
+keyboards, but should not be used in any new keyboards or user interfaces.
+
+[`GetLastActiveElement` or `getLastActiveElement` Function (Deprecated)](GetLastActiveElement)
+:   Use [`keyman.interface.getLastActiveTextStore()`](getLastActiveTextStore)
+
+[`FocusLastActiveElement` or `focusLastActiveElement` Function (Deprecated)](FocusLastActiveElement)
+:   Use [`keyman.interface.focusLastActiveTextStore()`](focusLastActiveTextStore)
+
+[`HideHelp` or `hideHelp` Function (Deprecated)](HideHelp)
+:   Use [`keyman.osk.hide()`](../osk/hide)
+
+[`ShowHelp` or `showHelp` Function (Deprecated)](ShowHelp)
+:   Use [`keyman.osk.setPos()`](../osk/setPos)
+    Use [`keyman.osk.show()`](../osk/show)
+
+[`ShowPinnedHelp` or `showPinnedHelp` Function (Deprecated)](ShowPinnedHelp)
+:   Use [`keyman.osk.setRect()`](../osk/setRect)
+:   Use [`keyman.osk.show()`](../osk/show)

web/src/app/browser/src/keyboardInterface.ts

@@ -26,23 +26,27 @@ export class KeyboardInterface extends KeyboardInterfaceBase<ContextManager> {
     this.engine.contextManager.focusAssistant._IgnoreNextSelChange = 1;
   }
 
-  /**
-   * Legacy entry points (non-standard names)- included only to allow existing IME keyboards to continue to be used
-   */
-  getLastActiveElement(): AbstractElementTextStore<any> {
+  getLastActiveTextStore(): AbstractElementTextStore<any> {
     return this.engine.contextManager.lastActiveTextStore;
   }
 
-  focusLastActiveElement(): void {
+  focusLastActiveTextStore(): void {
     this.engine.contextManager.restoreLastActiveTextStore();
   }
 
   //The following entry points are defined but should not normally be used in a keyboard, as OSK display is no longer determined by the keyboard
+
+  /**
+   * @deprecated
+   */
   hideHelp(): void {
     const osk = this.engine.osk;
     osk.startHide(true);
   }
 
+  /**
+   * @deprecated
+   */
   showHelp(Px: number, Py: number): void {
     const osk = this.engine.osk;
 
@@ -53,6 +57,9 @@ export class KeyboardInterface extends KeyboardInterfaceBase<ContextManager> {
     }
   }
 
+  /**
+   * @deprecated
+   */
   showPinnedHelp(): void {
     const osk = this.engine.osk;
 
@@ -74,13 +81,6 @@ export class KeyboardInterface extends KeyboardInterfaceBase<ContextManager> {
     // pinned position.
     osk.present();
   }
-
-  // Also needed for some legacy CJK keyboards.
-  readonly GetLastActiveElement = this.getLastActiveElement;
-  readonly FocusLastActiveElement = this.focusLastActiveElement;
-  readonly HideHelp = this.hideHelp;
-  readonly ShowHelp = this.showHelp;
-  readonly ShowPinnedHelp = this.showPinnedHelp;
 }
 
 (function() {

web/src/app/browser/src/keymanEngine.ts

@@ -543,7 +543,7 @@ export class KeymanEngine extends KeymanEngineBase<BrowserConfiguration, Context
    * See https://help.keyman.com/developer/engine/web/current-version/reference/core/getLastActiveElement
    */
   public getLastActiveElement(): HTMLElement | null {
-    return this.contextManager.lastActiveTextStore?.getElement();
+    return this.contextManager.lastActiveTextStore?.getElement() ?? null;
   }
 
   /**

web/src/engine/src/main/keyboardInterfaceBase.ts

@@ -8,6 +8,7 @@ import { ContextManagerBase } from './contextManagerBase.js';
 import { VariableStoreCookieSerializer } from "./variableStoreCookieSerializer.js";
 import { KeymanEngineBase } from "./keymanEngineBase.js";
 import { EngineConfiguration } from "./engineConfiguration.js";
+import { type TextStore } from 'keyman/engine/keyboard';
 
 export class KeyboardInterfaceBase<ContextManagerType extends ContextManagerBase<any>> extends JSKeyboardInterface {
   protected readonly engine: KeymanEngineBase<EngineConfiguration, ContextManagerType, any>;
@@ -118,6 +119,92 @@ export class KeyboardInterfaceBase<ContextManagerType extends ContextManagerBase
 
   // Short-hand name: necessary to do it this way due to assignment style.
   KT = this.insertText;
+
+  /**
+   * Get the currently or most recently focused text store. This is for use by
+   * IME keyboards, to allow for more complex focus interactions when clicking
+   * IME elements.
+   *
+   * @returns the last active text store, or null
+   *
+   * See also {@link focusLastActiveTextStore}
+   */
+  getLastActiveTextStore(): TextStore {
+    return this.engine.contextManager.activeTextStore;
+  }
+
+  /**
+   * Set focus to the currently-focused or most recently focused text store.
+   * This is for use, for example, by IME keyboards to return the focus to the
+   * text store after the user clicks on an IME element, without resetting
+   * context.
+   *
+   * See also {@link getLastActiveTextStore}
+   */
+  focusLastActiveTextStore(): void {
+    // no op in base
+  }
+
+  /**
+   * Warning: this function returns a `TextStore`, not a `HTMLElement`. Instead,
+   * use {@link getLastActiveTextStore}
+   * @deprecated see {@link getLastActiveTextStore}
+   */
+  readonly getLastActiveElement = this.getLastActiveTextStore;
+
+  /**
+   * @deprecated see {@link focusLastActiveTextStore}
+   */
+  readonly focusLastActiveElement = this.focusLastActiveTextStore;
+
+  /**
+   * @deprecated
+   */
+  hideHelp(): void {
+    // no op in base
+  }
+
+  /**
+   * @deprecated
+   */
+  showHelp(Px: number, Py: number): void {
+    // no op in base
+  }
+
+  /**
+   * @deprecated
+   */
+  showPinnedHelp(): void {
+    // no op in base
+  }
+
+  /**
+   * Warning: this function returns a `TextStore`, not a `HTMLElement`. Instead,
+   * use {@link getLastActiveTextStore}
+   * @deprecated see {@link getLastActiveTextStore}
+   */
+  readonly GetLastActiveElement = this.getLastActiveTextStore;
+
+  /**
+   * @deprecated see {@link focusLastActiveTextStore}
+   */
+  readonly FocusLastActiveElement = this.focusLastActiveTextStore;
+
+  // Also needed for some legacy CJK keyboards.
+  /**
+   * @deprecated
+   */
+  readonly HideHelp = this.hideHelp;
+
+  /**
+   * @deprecated
+   */
+  readonly ShowHelp = this.showHelp;
+
+  /**
+   * @deprecated
+   */
+  readonly ShowPinnedHelp = this.showPinnedHelp;
 }
 
 (function() {