Allow preventing default handlers for key events (zauberzeug#5222)

### Motivation

In zauberzeug#4924 @samuller mentioned that the "/" key on the NiceGUI website
doesn't work flawlessly to open the search dialog on Firefox because the
default handler opens Firefox' built-in search field. We also discussed
how to bring the `preventDefault()` and `stopPropagation()` functions to
`ui.keyboard`.

### Implementation

- This PR adds the original JavaScript event object to the argument
dictionary which is passed to `js_handler`.
- A new demo shows how to use `.on('key', ..., js_handler=...)` to
handle key events on the client and conditionally call
`preventDefault()` or `stopPropagation()`.
- A similar `js_handler` function is used to improve the "/" key
behavior on the NiceGUI website.
- The formatting of some version specifiers is fixed.

### Progress

- [x] I chose a meaningful title that completes the sentence: "If
applied, this PR will..."
- [x] The implementation is complete.
- [x] Pytests are not necessary.
- [x] Documentation has been added.

Author: falkoschindler

nicegui/elements/button_dropdown.py

@@ -55,7 +55,7 @@ def __init__(self,
     def on_click(self, callback: Handler[ClickEventArguments]) -> Self:
         """Add a callback to be invoked when the dropdown button is clicked.
 
-        **Added in version 2.22.0**
+        *Added in version 2.22.0*
         """
         self.on('click', lambda _: handle_event(callback, ClickEventArguments(sender=self, client=self.client)), [])
         return self

nicegui/elements/fab.py

@@ -59,7 +59,7 @@ def __init__(self, icon: str, *,
         An action that can be added to a floating action button (FAB).
         This element is based on Quasar's `QFabAction <https://quasar.dev/vue-components/floating-action-button#qfabaction-api>`_ component.
 
-        **Added in version 2.22.0**
+        *Added in version 2.22.0*
 
         :param icon: icon to be displayed on the action button
         :param label: optional label for the action button

nicegui/elements/keyboard.js

@@ -12,6 +12,7 @@ export default {
         if (evt.repeat && !this.repeating) return;
 
         this.$emit("key", {
+          event: evt,
           action: event,
           altKey: evt.altKey,
           ctrlKey: evt.ctrlKey,

website/documentation/content/keyboard_documentation.py

@@ -28,4 +28,23 @@ def handle_key(e: KeyEventArguments):
     ui.checkbox('Track key events').bind_value_to(keyboard, 'active')
 
 
+@doc.demo('Prevent default and stop propagation', '''
+    You can use the `js_handler` parameter of the `on` method to control how an event is handled on the client side.
+    To prevent the default behavior, you can call the `preventDefault` method of the `event` object.
+    To stop the propagation of the event, you could also call the `stopPropagation` method of the `event` object.
+
+    *Added in version 3.1.0*
+''')
+def prevent_default() -> None:
+    ui.label('Select via Ctrl-A or Cmd-A is disabled')
+
+    ui.keyboard() \
+        .on('key', lambda: ui.notify('Select all prevented.'), js_handler='''(e) => {
+            if (e.key === 'a' && (e.ctrlKey || e.metaKey) && e.action === 'keydown') {
+                emit(e);
+                e.event.preventDefault();
+            }
+        }''')
+
+
 doc.reference(ui.keyboard)

website/search.py

@@ -39,20 +39,18 @@ def __init__(self) -> None:
                     .props('padding="2px 8px" outline size=sm color=grey-5').classes('shadow')
             ui.separator()
             self.results = ui.element('q-list').classes('w-full').props('separator')
-        ui.keyboard(self.handle_keypress)
+        ui.keyboard().on('key', self.dialog.open, js_handler='''(e) => {
+            if (e.action !== 'keydown') return;
+            if (e.key === '/' || (e.key === 'k' && (e.ctrlKey || e.metaKey))) {
+                emit(e);
+                e.event.preventDefault();
+            }
+        }''')
 
     def create_button(self) -> ui.button:
         return ui.button(on_click=self.dialog.open, icon='search').props('flat color=white') \
             .tooltip('Press Ctrl+K or / to search the documentation')
 
-    def handle_keypress(self, e: events.KeyEventArguments) -> None:
-        if not e.action.keydown:
-            return
-        if e.key == '/':
-            self.dialog.open()
-        if e.key == 'k' and (e.modifiers.ctrl or e.modifiers.meta):
-            self.dialog.open()
-
     def handle_input(self, e: events.ValueChangeEventArguments) -> None:
         async def handle_input() -> None:
             with self.results: