rename capture_events parameter to event_order

frontend/code/components/pointerEventListener.ts

@@ -20,7 +20,7 @@ export type PointerEventListenerState = ComponentState & {
     reportDragMove: boolean;
     reportDragEnd: boolean;
     consume_events: boolean;
-    capture_events: boolean;
+    event_order: "before-child" | "after-child";
 };
 
 const DOUBLE_CLICK_TIMEOUT = 300;
@@ -31,7 +31,7 @@ export class PointerEventListenerComponent extends ComponentBase<PointerEventLis
         [button: number]: number | undefined;
     } = {};
     // Handler references created on-demand where installed
-    private _onClickBound: (e: MouseEvent) => void | null = null;
+    private _onClickBound: ((e: MouseEvent) => void) | null = null;
     private _onPointerDownBound: ((e: PointerEvent) => void) | null = null;
     private _onPointerUpBound: ((e: PointerEvent) => void) | null = null;
     private _onPointerMoveBound: ((e: PointerEvent) => void) | null = null;
@@ -55,19 +55,18 @@ export class PointerEventListenerComponent extends ComponentBase<PointerEventLis
         if (
             deltaState.reportPress !== undefined ||
             deltaState.reportDoublePress !== undefined ||
-            deltaState.capture_events !== undefined
+            deltaState.event_order !== undefined
         ) {
             const reportPress =
                 deltaState.reportPress ?? this.state.reportPress;
             const reportDoublePress =
                 deltaState.reportDoublePress ?? this.state.reportDoublePress;
-            const captureEvents =
-                deltaState.capture_events ?? this.state.capture_events;
+            const eventOrder = deltaState.event_order ?? this.state.event_order;
 
             this._onClickBound = this._updateEventListener(
                 "click",
                 reportPress || reportDoublePress,
-                captureEvents,
+                eventOrder,
                 this._onClickBound,
                 this._onClick
             );
@@ -75,12 +74,12 @@ export class PointerEventListenerComponent extends ComponentBase<PointerEventLis
 
         if (
             deltaState.reportPointerDown !== undefined ||
-            deltaState.capture_events !== undefined
+            deltaState.event_order !== undefined
         ) {
             const reportPointerDown =
                 deltaState.reportPointerDown ?? this.state.reportPointerDown;
             const captureEvents =
-                deltaState.capture_events ?? this.state.capture_events;
+                deltaState.event_order ?? this.state.event_order;
 
             this._onPointerDownBound = this._updateEventListener(
                 "pointerdown",
@@ -93,12 +92,12 @@ export class PointerEventListenerComponent extends ComponentBase<PointerEventLis
 
         if (
             deltaState.reportPointerUp !== undefined ||
-            deltaState.capture_events !== undefined
+            deltaState.event_order !== undefined
         ) {
             const reportPointerUp =
                 deltaState.reportPointerUp ?? this.state.reportPointerUp;
             const captureEvents =
-                deltaState.capture_events ?? this.state.capture_events;
+                deltaState.event_order ?? this.state.event_order;
 
             this._onPointerUpBound = this._updateEventListener(
                 "pointerup",
@@ -111,12 +110,12 @@ export class PointerEventListenerComponent extends ComponentBase<PointerEventLis
 
         if (
             deltaState.reportPointerMove !== undefined ||
-            deltaState.capture_events !== undefined
+            deltaState.event_order !== undefined
         ) {
             const reportPointerMove =
                 deltaState.reportPointerMove ?? this.state.reportPointerMove;
             const captureEvents =
-                deltaState.capture_events ?? this.state.capture_events;
+                deltaState.event_order ?? this.state.event_order;
 
             this._onPointerMoveBound = this._updateEventListener(
                 "pointermove",
@@ -129,12 +128,12 @@ export class PointerEventListenerComponent extends ComponentBase<PointerEventLis
 
         if (
             deltaState.reportPointerEnter !== undefined ||
-            deltaState.capture_events !== undefined
+            deltaState.event_order !== undefined
         ) {
             const reportPointerEnter =
                 deltaState.reportPointerEnter ?? this.state.reportPointerEnter;
             const captureEvents =
-                deltaState.capture_events ?? this.state.capture_events;
+                deltaState.event_order ?? this.state.event_order;
 
             this._onPointerEnterBound = this._updateEventListener(
                 "pointerenter",
@@ -147,12 +146,12 @@ export class PointerEventListenerComponent extends ComponentBase<PointerEventLis
 
         if (
             deltaState.reportPointerLeave !== undefined ||
-            deltaState.capture_events !== undefined
+            deltaState.event_order !== undefined
         ) {
             const reportPointerLeave =
                 deltaState.reportPointerLeave ?? this.state.reportPointerLeave;
             const captureEvents =
-                deltaState.capture_events ?? this.state.capture_events;
+                deltaState.event_order ?? this.state.event_order;
 
             this._onPointerLeaveBound = this._updateEventListener(
                 "pointerleave",
@@ -167,14 +166,13 @@ export class PointerEventListenerComponent extends ComponentBase<PointerEventLis
             deltaState.reportDragStart !== undefined ||
             deltaState.reportDragMove !== undefined ||
             deltaState.reportDragEnd !== undefined ||
-            deltaState.capture_events !== undefined
+            deltaState.event_order !== undefined
         ) {
             let reportDrag =
                 (deltaState.reportDragStart ?? this.state.reportDragStart) ||
                 (deltaState.reportDragMove ?? this.state.reportDragMove) ||
                 (deltaState.reportDragEnd ?? this.state.reportDragEnd);
-            let captureEvents =
-                deltaState.capture_events ?? this.state.capture_events;
+            let eventOrder = deltaState.event_order ?? this.state.event_order;
 
             if (this._dragHandler !== null) {
                 this._dragHandler.disconnect();
@@ -187,7 +185,7 @@ export class PointerEventListenerComponent extends ComponentBase<PointerEventLis
                     onStart: this._onDragStart.bind(this),
                     onMove: this._onDragMove.bind(this),
                     onEnd: this._onDragEnd.bind(this),
-                    capturing: captureEvents,
+                    capturing: eventOrder === "before-child",
                 });
             }
         }
@@ -297,7 +295,9 @@ export class PointerEventListenerComponent extends ComponentBase<PointerEventLis
     /// Not all types of events are supported on the Python side. For example,
     /// pen input isn't currently handled. If this particular event isn't
     /// supported, returns `null`.
-    serializePointerEvent(event: PointerEvent | MouseEvent): object | null {
+    serializePointerEvent(
+        event: PointerEvent | MouseEvent
+    ): Record<string, string | number | null> | null {
         // Convert the pointer type
         //
         // Some browsers (e.g. Safari) sometimes have `undefined` as the pointer
@@ -394,14 +394,14 @@ export class PointerEventListenerComponent extends ComponentBase<PointerEventLis
     private _updateEventListener<T extends Event>(
         eventName: string,
         shouldInstall: boolean,
-        captureEvents: boolean,
+        eventOrder: "before-child" | "after-child",
         currentHandler: ((e: T) => void) | null,
         callbackMethod: (this: PointerEventListenerComponent, e: T) => void
     ): ((e: T) => void) | null {
         // Remove existing listener if it exists
         if (currentHandler !== null) {
             this.element.removeEventListener(eventName, currentHandler, {
-                capture: this.state.capture_events,
+                capture: this.state.event_order === "before-child",
             });
         }
 
@@ -412,7 +412,7 @@ export class PointerEventListenerComponent extends ComponentBase<PointerEventLis
         // Install new listener with current capture setting
         const newHandler = callbackMethod.bind(this);
         this.element.addEventListener(eventName, newHandler, {
-            capture: captureEvents,
+            capture: eventOrder === "before-child",
         });
         return newHandler;
     }

rio/components/pointer_event_listener.py

@@ -172,13 +172,13 @@ class PointerEventListener(FundamentalComponent):
 
     `on_drag_end`: Triggered when the user stops dragging the pointer.
 
-    `consume_events`: If True, prevents the event from reaching other components
-        after this listener processes it.
+    `consume_events`: If `True`, prevents the event from reaching other
+        components after this listener processes it.
 
-    `capture_events`: Controls when this listener receives events relative to
-        its child components. When True, this listener's handlers are called
-        before any child component handlers. When False (default), child
-        components receive events first, then this listener.
+    `event_order`: Controls when this listener receives events relative to
+        its child components. When `"before-child"`, this listener's handlers
+        are called before any child component handlers. When `"after-child"`
+        (default), child components receive events first, then this listener.
     """
 
     content: rio.Component
@@ -200,7 +200,7 @@ class PointerEventListener(FundamentalComponent):
     on_drag_move: rio.EventHandler[PointerMoveEvent] = None
     on_drag_end: rio.EventHandler[PointerEvent] = None
     consume_events: bool = True
-    capture_events: bool = False
+    event_order: t.Literal["before-child", "after-child"] = "after-child"
 
     def _custom_serialize_(self) -> JsonDoc:
         return {

tests/test_frontend/test_pointer_event_listener.py

@@ -71,12 +71,12 @@ async def test_on_double_press_event(
 )
 @pytest.mark.parametrize("pressed_button", ["left", "middle", "right"])
 @pytest.mark.parametrize("consume_events", [True, False])
-@pytest.mark.parametrize("capture_events", [True, False])
+@pytest.mark.parametrize("event_order", ["before-child", "after-child"])
 async def test_specific_button_events(
     event_buttons: t.Sequence[t.Literal["left", "middle", "right"]],
     pressed_button: t.Literal["left", "middle", "right"],
     consume_events: bool,
-    capture_events: bool,
+    event_order: t.Literal["before-child", "after-child"],
 ) -> None:
     down_events: list[rio.PointerEvent] = []
     up_events: list[rio.PointerEvent] = []
@@ -103,15 +103,19 @@ async def test_specific_button_events(
             },
             on_pointer_up={button: on_pointer_up for button in event_buttons},
             consume_events=consume_events,
-            capture_events=capture_events,
+            event_order=event_order,
         )
 
     async with BrowserClient(build) as client:
         await client.click(0.5, 0.5, button=pressed_button, sleep=0.5)
 
     if pressed_button in event_buttons:
-        assert len(down_events) == 1 + (capture_events and not consume_events)
-        assert len(up_events) == 1 + (capture_events and not consume_events)
+        assert len(down_events) == 1 + (
+            event_order == "before-child" and not consume_events
+        )
+        assert len(up_events) == 1 + (
+            event_order == "before-child" and not consume_events
+        )
     else:
         assert len(down_events) == 0
         assert len(up_events) == 0