Add a FocusSemanticEvent (#126171)

issue: #94523
engine pr: https://github.com/flutter/engine/pull/41777

packages/flutter/lib/src/semantics/semantics_event.dart

@@ -159,3 +159,71 @@ class TapSemanticEvent extends SemanticsEvent {
   @override
   Map<String, dynamic> getDataMap() => const <String, dynamic>{};
 }
+
+/// An event to move the accessibility focus.
+///
+/// Using this API is generally not recommended, as it may break a users' expectation of
+/// how a11y focus works and therefore should be just very carefully.
+///
+/// One possibile use case:
+/// For example, the currently focused rendering object is replaced by another rendering
+/// object. In general, such design should be avoided if possible. If not, one may want
+/// to refocus the newly added rendering object.
+///
+/// One example that is not recommended:
+/// When a new popup or dropdown opens, moving the focus in these cases may confuse users
+/// and make it less accessible.
+///
+/// {@tool snippet}
+///
+/// The following code snippet shows how one can request focus on a
+/// certain widget.
+///
+/// ```dart
+/// class MyWidget extends StatefulWidget {
+///   const MyWidget({super.key});
+///
+///   @override
+///   State<MyWidget> createState() => _MyWidgetState();
+/// }
+///
+/// class _MyWidgetState extends State<MyWidget> {
+///   bool noticeAccepted = false;
+///   final GlobalKey mykey = GlobalKey();
+///
+///   @override
+///   void initState() {
+///     super.initState();
+///     // Using addPostFrameCallback because changing focus need to wait for the widget to finish rendering.
+///     WidgetsBinding.instance.addPostFrameCallback((_) {
+///       mykey.currentContext?.findRenderObject()?.sendSemanticsEvent(const FocusSemanticEvent());
+///     });
+///   }
+///
+///   @override
+///   Widget build(BuildContext context) {
+///     return Scaffold(
+///       appBar: AppBar(
+///         title: const Text('example'),
+///       ),
+///       body: Column(
+///         children: <Widget>[
+///           const Text('Hello World'),
+///           const SizedBox(height: 50),
+///           Text('set focus here', key: mykey),
+///         ],
+///       ),
+///     );
+///   }
+/// }
+/// ```
+/// {@end-tool}
+///
+/// This currently only supports Android and iOS.
+class FocusSemanticEvent extends SemanticsEvent {
+  /// Constructs an event that triggers a focus change by the platform.
+  const FocusSemanticEvent() : super('focus');
+
+  @override
+  Map<String, dynamic> getDataMap() => const <String, dynamic>{};
+}

packages/flutter/test/widgets/semantics_event_test.dart

@@ -47,6 +47,15 @@ void main() {
       },
     );
   });
+  test('FocusSemanticEvent.toMap', () {
+    expect(
+      const FocusSemanticEvent().toMap(),
+      <String, dynamic>{
+        'type': 'focus',
+        'data': <String, dynamic>{},
+      },
+    );
+  });
 }
 
 class TestSemanticsEvent extends SemanticsEvent {