Skip to content

Commit 855cb10

Browse files
committed
[web] Don't debounce physical mouse clicks in ClickDebouncer
When semantics is enabled, `ClickDebouncer` withholds pointer events that land on an `flt-tappable` node and, on the subsequent DOM "click", synthesizes a generic `SemanticsAction.tap` in their place. The framework turns that into a tap at the center of the widget with `PointerDeviceKind.unknown`, so a `GestureDetector` under a physical mouse cursor reports `Tap*Details` with the wrong position and kind. Forward physical mouse input straight to the framework instead. The subsequent "click" is then deduped by `_shouldSendClickEventToFramework`, because the forwarded `pointerup` sets `_lastSentPointerUpTimeStamp`. Trade-off, documented at the call site: mouse input can no longer reach `SemanticsAction.tap` by any route, so a semantics node exposing a tap action with no hit-testable gesture recognizer under the cursor stops responding to mouse clicks. Only `mouse` is exempted; `pen` and `touch` still debounce. Also removes a 200ms delay on every mouse press over a tappable node. Tests: the existing `_testClickDebouncer` cases were written against `context.primaryDown()`, which is `pointerType: 'mouse'`, so they now exercise touch instead via local `touchDown`/`touchUp` helpers. Adds a regression test that mouse input reaches the framework as pointer packets and that the following "click" does not also fire a semantics tap. Fixes flutter#188859
1 parent de6cb8b commit 855cb10

2 files changed

Lines changed: 82 additions & 14 deletions

File tree

‎engine/src/flutter/lib/web_ui/lib/src/engine/pointer_binding.dart‎

Lines changed: 46 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -215,6 +215,11 @@ typedef DebounceState = ({
215215
/// gesture.
216216
///
217217
/// This mechanism is in place to deal with https://github.com/flutter/flutter/issues/130162.
218+
///
219+
/// Physical mouse input is exempt from all of the above and is forwarded to
220+
/// the framework directly, because a synthesized `SemanticsAction.tap` loses
221+
/// the pointer position and device kind that a mouse gesture carries. See
222+
/// [_maybeStartDebouncing].
218223
class ClickDebouncer {
219224
ClickDebouncer() {
220225
assert(() {
@@ -255,7 +260,8 @@ class ClickDebouncer {
255260
/// debouncing and flushes pointer events to the framework.
256261
///
257262
/// If the event is a `pointerdown` and the target is `flt-tappable`, begins
258-
/// debouncing events.
263+
/// debouncing events, unless the event came from a physical mouse, which is
264+
/// never debounced.
259265
///
260266
/// In all other situations forwards the event to the framework.
261267
void onPointerData(DomEvent event, List<ui.PointerData> data) {
@@ -337,7 +343,7 @@ class ClickDebouncer {
337343
}
338344

339345
/// Starts debouncing pointer events if the [event] is a `pointerdown` on a
340-
/// tappable element.
346+
/// tappable element and did not come from a physical mouse.
341347
///
342348
/// To work around an issue in iOS Safari, the debouncing does not start
343349
/// immediately, but at the end of the event loop.
@@ -349,6 +355,39 @@ class ClickDebouncer {
349355
assert(!isDebouncing, 'Cannot start debouncing. Already debouncing.');
350356
assert(event.type == 'pointerdown', 'Click debouncing must begin with a pointerdown');
351357

358+
// Physical mouse input is never debounced.
359+
//
360+
// The debouncer resolves the pointer-events-vs-"click" ambiguity by
361+
// dropping the pointer events and synthesizing a generic
362+
// `SemanticsAction.tap` in their place. That trade is right for an
363+
// assistive technology, which only wants to activate the node, but it is
364+
// wrong for a real mouse: the synthesized tap carries no position and no
365+
// device kind, so a `GestureDetector` under the cursor reports
366+
// `Tap*Details` pointing at the center of the screen with
367+
// `PointerDeviceKind.unknown`.
368+
//
369+
// The trade-off this makes: the forwarded `pointerup` sets
370+
// `_lastSentPointerUpTimeStamp`, so the "click" that follows is dropped by
371+
// [_shouldSendClickEventToFramework]. Mouse input therefore no longer
372+
// reaches `SemanticsAction.tap` by any route. A semantics node that
373+
// exposes a tap action but has no hit-testable gesture recognizer under
374+
// the cursor will not respond to a physical mouse click. That is
375+
// deliberate: coordinate-accurate taps are worth more than the
376+
// recognizer-less case, which the framework can express with a real
377+
// gesture detector.
378+
//
379+
// Only `mouse` is exempted, not `pen` or `touch`. Those are also physical
380+
// input and lose the same detail, but they are the input types the
381+
// debounce window was originally tuned against, and touch is the case the
382+
// debouncer was written for. Widening the exemption is a larger behavior
383+
// change than this fix warrants; see the discussion on the issue below.
384+
//
385+
// https://github.com/flutter/flutter/issues/188859
386+
if ((event as DomPointerEvent).pointerType == 'mouse') {
387+
_sendToFramework(event, data);
388+
return;
389+
}
390+
352391
final DomEventTarget? target = event.target;
353392
if (target.isA<DomElement>() && (target! as DomElement).hasAttribute('flt-tappable')) {
354393
_isDebouncing = true;
@@ -403,6 +442,11 @@ class ClickDebouncer {
403442
// * It was long enough to register taps and clicks.
404443
// * It was successful at detecting taps generated by all tested
405444
// screen readers.
445+
//
446+
// Note: physical mouse input no longer reaches this timer at all; it is
447+
// forwarded to the framework from [_maybeStartDebouncing]. The mouse and
448+
// trackpad cases above are retained as a record of how the window was
449+
// originally tuned.
406450
timer: Timer(const Duration(milliseconds: 200), _onTimerExpired),
407451
);
408452
}

‎engine/src/flutter/lib/web_ui/test/engine/pointer_binding_test.dart‎

Lines changed: 36 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3128,27 +3128,51 @@ void _testClickDebouncer({required PointerBinding Function() getBinding}) {
31283128
expect(semanticsActions, isEmpty);
31293129
});
31303130

3131-
testWithSemantics('Forwards to framework when pointerType is mouse', () async {
3131+
// Regression test for https://github.com/flutter/flutter/issues/188859
3132+
testWithSemantics('Forwards physical mouse input to the framework', () async {
31323133
expect(EnginePlatformDispatcher.instance.semanticsEnabled, true);
31333134
expect(PointerBinding.clickDebouncer.isDebouncing, false);
31343135

31353136
final DomElement testElement = createDomElement('flt-semantics');
31363137
testElement.setAttribute('flt-tappable', '');
31373138
view.dom.semanticsHost.appendChild(testElement);
31383139

3139-
// context.primaryDown/Up simulate pointerType: "mouse"
3140-
testElement.dispatchEvent(context.primaryDown());
3140+
testElement.dispatchEvent(context.mouseDown(button: 0, buttons: 1));
3141+
expect(
3142+
reason: 'A physical mouse must not start debouncing.',
3143+
PointerBinding.clickDebouncer.isDebouncing,
3144+
isFalse,
3145+
);
3146+
31413147
await nextEventLoop();
3142-
testElement.dispatchEvent(context.primaryUp());
3143-
expect(PointerBinding.clickDebouncer.isDebouncing, false);
3148+
testElement.dispatchEvent(context.mouseUp(button: 0));
3149+
expect(PointerBinding.clickDebouncer.isDebouncing, isFalse);
31443150

3145-
expect(pointerPackets, <ui.PointerChange>[
3146-
ui.PointerChange.add,
3147-
ui.PointerChange.down,
3148-
ui.PointerChange.up,
3149-
]);
3150-
expect(semanticsActions, isEmpty);
3151-
});
3151+
expect(
3152+
reason:
3153+
'Pointer events reach the framework with real coordinates, so a '
3154+
'GestureDetector can report accurate Tap*Details.',
3155+
pointerPackets,
3156+
<ui.PointerChange>[ui.PointerChange.add, ui.PointerChange.down, ui.PointerChange.up],
3157+
);
3158+
3159+
// The browser follows the pointer events with a DOM "click". It must not
3160+
// also be turned into a SemanticsAction.tap, or the tap would fire twice.
3161+
final DomEvent click = createDomMouseEvent('click', <Object?, Object?>{
3162+
'clientX': testElement.getBoundingClientRect().x,
3163+
'clientY': testElement.getBoundingClientRect().y,
3164+
});
3165+
PointerBinding.clickDebouncer.onClick(click, view.viewId, 42, true);
3166+
3167+
expect(
3168+
reason:
3169+
'Because the DOM click event was deduped against the pointerup that '
3170+
'was just flushed.',
3171+
semanticsActions,
3172+
isEmpty,
3173+
);
3174+
// TODO(yjbanov): https://github.com/flutter/flutter/issues/142991.
3175+
}, skip: ui_web.browser.operatingSystem == ui_web.OperatingSystem.windows);
31523176

31533177
testWithSemantics('Does not start debouncing if reset before scheduled execution', () async {
31543178
expect(EnginePlatformDispatcher.instance.semanticsEnabled, isTrue);

0 commit comments

Comments
 (0)