spec: Text Selection and Key Processing

## Text Selection, Key processing and Keyman Core

Note: `⁞` here is used to delineate text selection throughout this spec:
* One `⁞` indicates the text caret without a selection; or
* Text between two `⁞` is selected.

For 'legacy' apps, where we do not have data about text selection or context prior to the selected text, none of this information applies. This information is only about 'modern' apps which supply context (e.g. on Windows, TSF-aware apps).

## Related issues
- [ ] [#8827](https://github.com/keymanapp/keyman/issues/8827) bug(linux): Backspace doesn't work properly with text selection
- ✔ [#5853](https://github.com/keymanapp/keyman/issues/5853) bug(web): Highlight and replace/delete is not working
- ✔ [#6177](https://github.com/keymanapp/keyman/issues/6177) bug: iOS and Android Text Select weird behavior
- ✔ [#6261](https://github.com/keymanapp/keyman/issues/6261) bug(android): selection is not deleted when typing, and existing text becomes undeletable
- [ ] [#7161](https://github.com/keymanapp/keyman/issues/7161) meta(android): team review of Android UX
- [ ] [#7168](https://github.com/keymanapp/keyman/issues/7168) feat(android): when selecting text, the keyboard has no context and thus gives Initial case, usually wrongly
- [ ] [#7865](https://github.com/keymanapp/keyman/issues/7865) bug(iOS): selecting text and then backspacing also deletes the character before the selection
- [ ] [#7866](https://github.com/keymanapp/keyman/issues/7866) bug(web): text selection + typing interaction issues
- Comes to a similar conclusion re: selected text -> backspace
- ([#7866 \[comment\]](https://github.com/keymanapp/keyman/issues/7866#issuecomment-1471546855))
- [ ] [#7870](https://github.com/keymanapp/keyman/issues/7870) bug(windows): backspace with selected text deletes an extra character in TSF only
## Related pull requests
- ✖ [~~PR#5854~~](https://github.com/keymanapp/keyman/pull/5854) fix(web): Allow touch-alias elements to clear text selection
- ✖ [~~PR#5922~~](https://github.com/keymanapp/keyman/issues/5922) fix(android/engine): Don't pass selected text to KeymanWeb
- ✔ [PR#6272](https://github.com/keymanapp/keyman/pull/6272) fix(web): properly handle selection
- ✔ [PR#6274](https://github.com/keymanapp/keyman/pull/6274) fix(android): properly handle selection
- ✔ [PR#6280](https://github.com/keymanapp/keyman/pull/6280) fix(ios): properly handle selection
- ✔ [PR#8462](https://github.com/keymanapp/keyman/pull/8462) feat(common/web): mocks may now model selected text
- ✔ [PR#8611](https://github.com/keymanapp/keyman/pull/8611) fix(android/engine): Fix resetContext calls when selection changes

## Introduction

When a user selects text then presses a key; either a Backspace or a Character Key we need to define the expect result. Looking at a variety of scenarios and the current related issues makes it clear that we could:

a) over complicate the expected behaviour unnecessarily.

b) have many edge cases, touch, start of sentence etc

This specification will describe the way Keyman handles processing when a section of text is selected and then a key is pressed. Followed by some example scenarios.

## Specification

1. Backspace with a selection shall not trigger keystroke rules
1. It shall trigger `newcontext` because a text-changing event has occurred which is outside the engines control. (as the backspace will be passed to the app so it can delete text as required, e.g. a selection across multiple fields or a multi-selection)
1. For **character-generating keystrokes** with selection. The selection shall be masked from the context, and apply rules to the resulting context (see example 2).
1. Note: implementation in Engine means we may need to do output a backspace to delete the selection before applying actions. (For legacy apps)
2. For 'context-aware' apps, we'll still need to delete the selection before applying actions.

## Applied Examples
- How do we treat context when we have a selection?

- Example: `⁞^⁞` in doc, selection as indicated.

Typing A result: `A⁞`.

- Example: `^⁞X⁞` in doc.

Typing A result: `Â⁞`

- Example: `^⁞X the quick brown fox⁞` in doc.

Typing A give us `Â⁞`

- Example: `^⁞X the quick brown fox⁞` in doc.

Typing Backspace, then A, result: `Â⁞`

- Example: `^⁞X the quick brown fox⁞A` in doc.

Typing Backspace give us `^⁞A`

# Additional questions and answers

- What shift state should we give the keyboard on touch keyboards when we have a selection?
- `Hello. ⁞world⁞`, note that 'world' is lower-case, but a sentence-aware keyboard would expect to start a new sentence due to the full stop prior. So, with a selection, should the touch keyboard go to shift layer to match 'start of sentence'?
- This would trigger start-of-sentence. Doing the text selection would trigger `begin newcontext`, and be given the context `Hello. ` Thus, a sentence-aware keyboard would set the touch keyboard to the Shift layer.

- What should Backspace do when there is a selection?
- It should always delete the selection and not run the keyboard rule processing; in effect it has the same behavior as pressing Del (forward-delete).

## Future solution not covered by this specification -- `&hasSelection`

- Suggestion for the future: add a `&hasSelection` system store. And `&intent` (text,number,etc) would be nice to throw in.

- Until we implement `&hasSelection`, the answer is to apply keyboard rules (thus, the Example 2 above), except for Backspace, which behaves the same as Delete.
- Adding the `&hasSelection` flag allows keyboard authors to override the default, and will allow them to process Backspace or Delete when there is a selection, and provide a sensible result. This will require updating the keyboard `&version` to `vX.Y` (the version where we introduce this feature).
- We will need to work through the edge cases carefully here when we implement this.

## Reference

* https://docs.google.com/document/d/1qDmJHInvyYm-7apAzzvkwC2BOHf8DUOaPI_sPSxmeg4/edit
* [Test matrix](https://docs.google.com/spreadsheets/d/1NDO82y77C45pw_ZcMPcD36NZ4VUy9hQcuByieyeJVtM/edit?usp=sharing)
* [Compatibility Testing A19S24](https://docs.google.com/document/d/1oWsE8V2or8mBqqJMju3em5D_x7l0V0N8Ry1Iq4x77IY/edit?tab=t.0)