Description

This pull request introduces a capture option for keybindings, allowing them to be processed during the capturing phase of the event propagation. This change aims to resolve complex keyboard shortcut conflicts between Lumino applications and other components that have their own keymap systems, such as CodeMirror.

This PR tries to address #761 and the original JupyterLab issue jupyterlab/jupyterlab#15897.

By handling certain keybindings in the capturing phase, we can intercept events before they reach components like CodeMirror, preventing them from being consumed and allowing Lumino's shortcut system to have precedence when needed.

I hope this PR can help clarify these issues and serve as a starting point for further discussion and improvements.

Code Changes

1. packages/commands/src/index.ts

   • Added capture property to IKeyBindingOptions and IKeyBinding: This boolean flag allows developers to specify that a keybinding should be evaluated during the event capturing phase. The default remains false for backward compatibility.
   • Updated processKeydownEvent to be phase-aware: The method now checks event.eventPhase to filter keybindings based on their capture flag, ensuring that capturing bindings are only matched in the capturing phase and non-capturing bindings in the bubbling phase.
   • Introduced _allowReplayInBubbling flag: A new internal flag, _allowReplayInBubbling, has been added to manage complex interactions between phases. When a keystroke sequence in the capturing phase results in a mismatch, this flag enables the suppressed events to be replayed and re-evaluated in the bubbling phase. This ensures that the event can still be processed by bubbling-phase listeners (e.g., in CodeMirror or Lumino itself), enabling fallback behaviors as demonstrated in the new test cases.

2. packages/application/src/index.ts

   • Removed this._bubblingKeydown: The application now always attaches both capturing and bubbling phase listeners to document.
   • The bubblingKeydown option in IStartOptions is preserved for API compatibility but is no longer used.

3. packages/commands/tests/src/index.spec.ts

   • Added a new test suite for phase interactions: Tests has been added to verify the interactions between Lumino's capturing bindings, Lumino's bubbling bindings, and an external keymap handler (mocking CodeMirror).
   • These tests demonstrate various scenarios, including precedence, masking, and complex chord resolutions, to ensure the new capture feature behaves as expected in realistic integration contexts. A brief summary of the tested cases is included below.

Use Cases & Scenarios Tested

To illustrate the capabilities and limitations of this feature, I have defined several key interaction scenarios between Lumino bindings and a mocked external handler (simulating CodeMirror). While this mock is not a full replacement for end-to-end testing in JupyterLab, it provides valuable insight into the expected behavior.

• Case 1: Precedence of Capturing Bindings

  • A multi-stroke capturing binding (['Ctrl K', 'Ctrl L']) takes precedence over a single-stroke capturing binding (['Ctrl K']), which in turn executes after a timeout. Both correctly mask bubbling and external bindings.

• Case 2: Masking by External Handlers

  • An external handler can intercept a keydown event and stop its propagation, preventing a Lumino bubbling binding from executing.

• Case 3: Distinct Chord Resolution

  • The system can correctly differentiate between two chords starting with the same prefix (e.g., Ctrl K, Ctrl M vs. Ctrl K, Ctrl L), allowing an external handler to process its chord even if a Lumino capturing binding shares the same prefix.

• Case 4: Chord Interruption and Timeout Execution

  • When the second key of a Lumino bubbling chord is intercepted by an external handler, the partially matched command from the first key (['Ctrl K']) is correctly executed after the timeout.

• Case 5 & 6: Greedy vs. Non-Greedy Capturing Bindings

  • A single-stroke capturing binding will "greedily" execute and mask longer chords with the same prefix.
  • However, this greedy behavior is suppressed if another multi-stroke capturing binding also shares that prefix, allowing for more complex ambiguity resolution.

• Case 7 & 8: Sequence Integrity

  • A Lumino chord is not broken by an unrelated capturing binding that matches its second key.
  • Conversely, a Lumino chord is broken if an external handler partially matches and stops propagation on the first key.

A Note on Testing

The externalHandler introduced in the unit tests simulates only a limited subset of CodeMirror's behavior to demonstrate the intended interactions. It is recommended that further integration tests be added on the JupyterLab side to validate the behavior with a real CodeMirror instance.

Potential Issue for Consideration

The current implementation of processKeydownEvent relies on event.eventPhase. If event.target === event.currentTarget, the phase will be AT_TARGET (2), which our logic treats as the bubbling phase. In Lumino's application context, the listener is on document, so this is unlikely to be an issue. However, many of our existing unit tests dispatch events directly on the target element, creating this condition. If this PR is merged, a review of existing tests may be necessary to ensure they correctly simulate event propagation.