Expand touch area for Android selection handles (Resolves #2075) (#2079)

Author: matthew-carroll

super_editor/lib/src/default_editor/document_gestures_touch_android.dart

@@ -1679,6 +1679,9 @@ class SuperEditorAndroidControlsOverlayManagerState extends State<SuperEditorAnd
           link: _controlsController!.collapsedHandleFocalPoint,
           leaderAnchor: Alignment.bottomCenter,
           followerAnchor: Alignment.topCenter,
+          // Use the offset to account for the invisible expanded touch region around the handle.
+          offset: -Offset(0, AndroidSelectionHandle.defaultTouchRegionExpansion.top) *
+              MediaQuery.devicePixelRatioOf(context),
           child: AnimatedOpacity(
             // When the controller doesn't want the handle to be visible, hide it.
             opacity: shouldShow ? 1.0 : 0.0,
@@ -1726,6 +1729,9 @@ class SuperEditorAndroidControlsOverlayManagerState extends State<SuperEditorAnd
             link: _controlsController!.upstreamHandleFocalPoint,
             leaderAnchor: Alignment.bottomLeft,
             followerAnchor: Alignment.topRight,
+            // Use the offset to account for the invisible expanded touch region around the handle.
+            offset:
+                -AndroidSelectionHandle.defaultTouchRegionExpansion.topRight * MediaQuery.devicePixelRatioOf(context),
             child: GestureDetector(
               onTapDown: (_) {
                 // Register tap down to win gesture arena ASAP.
@@ -1755,6 +1761,9 @@ class SuperEditorAndroidControlsOverlayManagerState extends State<SuperEditorAnd
             link: _controlsController!.downstreamHandleFocalPoint,
             leaderAnchor: Alignment.bottomRight,
             followerAnchor: Alignment.topLeft,
+            // Use the offset to account for the invisible expanded touch region around the handle.
+            offset:
+                -AndroidSelectionHandle.defaultTouchRegionExpansion.topLeft * MediaQuery.devicePixelRatioOf(context),
             child: GestureDetector(
               onTapDown: (_) {
                 // Register tap down to win gesture arena ASAP.

super_editor/lib/src/infrastructure/platforms/android/selection_handles.dart

@@ -3,28 +3,71 @@ import 'dart:math';
 import 'package:flutter/material.dart';
 import 'package:super_editor/src/infrastructure/touch_controls.dart';
 
+/// An Android-style mobile selection drag handle.
+///
+/// Android renders three different types of handles: collapsed, upstream, and downstream.
+///
+/// All three types of handles look like 3/4 of a circle combined with 1/4 of a square (with
+/// a pointy corner). The primary difference between each handle appearance is the way the
+/// pointy corner is directed.
+///
+///  * Collapsed: The pointy corner points up.
+///  * Upstream: The pointy corner points to the upper right (marking the start of a selection).
+///  * Downstream: The pointy corner points to the upper left (marking the end of a selection).
 class AndroidSelectionHandle extends StatelessWidget {
+  static const defaultTouchRegionExpansion = EdgeInsets.only(left: 16, right: 16, bottom: 16);
+
   const AndroidSelectionHandle({
     Key? key,
     required this.handleType,
     required this.color,
     this.radius = 10,
+    this.touchRegionExpansion = defaultTouchRegionExpansion,
+    this.showDebugTouchRegion = false,
   }) : super(key: key);
 
+  /// The type of handle, e.g., collapsed, upstream, downstream.
   final HandleType handleType;
+
+  /// The color of the handle.
   final Color color;
+
+  /// The radius of the handle - each handle is essentially a circle with one pointy
+  /// corner.
   final double radius;
 
+  /// Invisible space added around the handle to increase the touch area the handle.
+  ///
+  /// This invisible area expands the intrinsic size of the handle, and therefore the
+  /// visual handle will no longer be aligned exactly with the content that's following.
+  /// The parent layout needs to adjust the positioning of the handle to account for
+  /// the [touchRegionExpansion].
+  final EdgeInsets touchRegionExpansion;
+
+  /// Whether to render the [touchRegionExpansion] with a translucent color for visual
+  /// debugging.
+  final bool showDebugTouchRegion;
+
   @override
   Widget build(BuildContext context) {
+    late final Widget handle;
     switch (handleType) {
       case HandleType.collapsed:
-        return _buildCollapsed();
+        handle = _buildCollapsed();
       case HandleType.upstream:
-        return _buildUpstream();
+        handle = _buildUpstream();
       case HandleType.downstream:
-        return _buildDownstream();
+        handle = _buildDownstream();
     }
+
+    return Container(
+      padding: touchRegionExpansion,
+      decoration: BoxDecoration(
+        shape: BoxShape.circle,
+        color: showDebugTouchRegion ? Colors.red.withOpacity(0.5) : Colors.transparent,
+      ),
+      child: handle,
+    );
   }
 
   Widget _buildCollapsed() {

super_editor/lib/src/super_textfield/android/_editing_controls.dart

@@ -716,22 +716,26 @@ class _AndroidEditingOverlayControlsState extends State<AndroidEditingOverlayCon
     required void Function(DragStartDetails) onPanStart,
   }) {
     late Offset fractionalTranslation;
+    late final Offset expandedTouchAreaAdjustment;
     switch (handleType) {
       case HandleType.collapsed:
         fractionalTranslation = const Offset(-0.5, 0.0);
+        expandedTouchAreaAdjustment = Offset(0, -AndroidSelectionHandle.defaultTouchRegionExpansion.top);
         break;
       case HandleType.upstream:
         fractionalTranslation = const Offset(-1.0, 0.0);
+        expandedTouchAreaAdjustment = -AndroidSelectionHandle.defaultTouchRegionExpansion.topRight;
         break;
       case HandleType.downstream:
         fractionalTranslation = Offset.zero;
+        expandedTouchAreaAdjustment = -AndroidSelectionHandle.defaultTouchRegionExpansion.topLeft;
         break;
     }
 
     return CompositedTransformFollower(
       key: handleKey,
       link: widget.textContentLayerLink,
-      offset: followerOffset,
+      offset: followerOffset + expandedTouchAreaAdjustment,
       child: FractionalTranslation(
         translation: fractionalTranslation,
         child: GestureDetector(

super_editor/test/super_editor/mobile/super_editor_android_overlay_controls_test.dart

@@ -2,6 +2,7 @@ import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:flutter_test_robots/flutter_test_robots.dart';
 import 'package:flutter_test_runners/flutter_test_runners.dart';
+import 'package:super_editor/src/infrastructure/platforms/android/selection_handles.dart';
 import 'package:super_editor/super_editor.dart';
 import 'package:super_editor/super_editor_test.dart';
 import 'package:super_text_layout/super_text_layout.dart';
@@ -126,6 +127,10 @@ void main() {
       // Ensure the toolbar isn't visible.
       expect(SuperEditorInspector.isMobileToolbarVisible(), isFalse);
 
+      // Wait for the collapsed handle to disappear so that it doesn't cover the
+      // line below.
+      await tester.pump(const Duration(seconds: 5));
+
       // Place the caret at the beginning of the second paragraph, at the same offset.
       await tester.placeCaretInParagraph("2", 0);
 
@@ -215,11 +220,13 @@ void main() {
       expect(SuperEditorInspector.findAllMobileDragHandles(), findsExactly(2));
       expect(
         tester.getTopLeft(SuperEditorInspector.findMobileDownstreamDragHandle()),
-        offsetMoreOrLessEquals(documentLayout.getGlobalOffsetFromDocumentOffset(selectedPositionRect.bottomRight)),
+        offsetMoreOrLessEquals(documentLayout.getGlobalOffsetFromDocumentOffset(selectedPositionRect.bottomRight) -
+            Offset(AndroidSelectionHandle.defaultTouchRegionExpansion.left, 0)),
       );
       expect(
         tester.getTopRight(SuperEditorInspector.findMobileUpstreamDragHandle()),
-        offsetMoreOrLessEquals(documentLayout.getGlobalOffsetFromDocumentOffset(selectedPositionRect.bottomRight)),
+        offsetMoreOrLessEquals(documentLayout.getGlobalOffsetFromDocumentOffset(selectedPositionRect.bottomRight) +
+            Offset(AndroidSelectionHandle.defaultTouchRegionExpansion.right, 0)),
       );
 
       // Release the drag handle.