Added keyboard text selection support

[oleksandr-danylchenko]

Issue

Previously, only the pointer-based selection was captured and processed by the SelectionHandler and the related TextAnnotatorPopup. When the user initiated the selection with the Shift + Arrow or Ctrl + A - it wasn't represented in the annotation selection state. Therefore, we couldn't know when or whether the annotation popup should appear.
Instead, for better a11y support, the selection should be able to start and conclude using exclusively keyboard events. The ability to start the selection anywhere on the page is already provided by the caret browsing mode.

Recommendations

Per a11y expert on our team, we received the following recommendations for the selection behavior:

Ideally, you could release shift, then press it again, and select some more text. This makes tracking Shift (rather than something admittedly awkward like Control Alt/Option h) tricky. But if you could leave focus on the page, and just open the popup when mouse is released or when the keyboard selection starts, and then leave it open through subsequent shift presses and shift clicks, and let users tab to the popup or click a close button or press escape to close the popup, that would work

Also, there were some recommendations on when the popup should be closed:

Since focus doesn't move into it automatically, I don't think it should be modal. It would be good if it only closes if:

• the text is unselected
• the user moves into it and then presses Escape
• the user moves into and presses a button that would normally close it (not sure it there is a close button - there doesn't have to be one, but it might be helpful)

Relations

• This PR depends on the:
  • #419 Selection event generalization annotorious/annotorious#420, which generalizes the user's selection event capturing.
  • Added annotation discarding when the selection collapses #140, which fixed leaving zombie annotations upon changing the selection direction.
  • #133 Fixed missing annotation dismissal clicking outside of the annotator container (vol.2) #149, which fixed reading obsolete isCollapsed value when processing pointerup event.
• After consulting with a11y UX expert there made a few popup behavior decisions - Generalize the SelectionState type to allow custom selection implementations annotorious/annotorious#419 (comment)
• Addresses the Ctrl + A doesn't make the annotation popup to appear #111

Changes Made

1. Generalized the lastPointerDown to just the lastDownEvent event, which preserves both the pointerdown and keydown events. Both can be used to create the annotation selection state within the onSelectionChange callback.
2. Added pre-defined focusing behavior into the TextAnnotatorPopup component using the FloatingFocusManager. Per @rsimon request, the automatic focus shift was tuned separately for the mouse and keyboard selection.
   For the mouse - the focus automatically goes to the first tabbable element within the floating to reduce the number of clicks required to jot down a note quickly.
   For the keyboard - the focus gets shifted to the floating only when a user explicitly presses the Tab key. That allows us to make pauses during the selection and not lose the selection range before moving the popup.
3. Replaced PointerSelectAction with UserSelectAction in re-exports and throughout the code.

Demo

Mouse selection

mouse_selection.mov

Keyboard selection

1. Selection followed by free arrow key navigation

keyboard_selection_arrow.mov

2. Selection followed by Esc keypress

keyboard_selection_esc.mov

3. Selection followed by navigation to the popup and pressing the "Close" button

keyboard_selectino_close_button.mov

4. Selection followed by tabbing through the popup and bumping into the hint about the dismissal

Screen.Recording.2024-08-21.at.19.47.15.mov

[oleksandr-danylchenko]

Even though spreading event returns only the { isTrusted } object - it tricks the Typescript into thinking that the "cloned event" has the PointerEvent type