CupertinoSearchTextField: Add interactive examples (#103042)

* `CupertinoSearchTextField`: Add interactive examples

* Update docs

examples/api/lib/cupertino/search_field/cupertino_search_field.0.dart

@@ -0,0 +1,62 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// Flutter code sample for CupertinoSearchTextField
+
+import 'package:flutter/cupertino.dart';
+
+void main() => runApp(const SearchTextFieldApp());
+
+class SearchTextFieldApp extends StatelessWidget {
+  const SearchTextFieldApp({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return const CupertinoApp(
+      theme: CupertinoThemeData(brightness: Brightness.light),
+      home: SearchTextFieldExample(),
+    );
+  }
+}
+
+class SearchTextFieldExample extends StatefulWidget {
+  const SearchTextFieldExample({Key? key}) : super(key: key);
+
+  @override
+  State<SearchTextFieldExample> createState() => _SearchTextFieldExampleState();
+}
+
+class _SearchTextFieldExampleState extends State<SearchTextFieldExample> {
+  late TextEditingController textController;
+
+  @override
+  void initState() {
+    super.initState();
+    textController = TextEditingController(text: 'initial text');
+  }
+
+  @override
+  void dispose() {
+    textController.dispose();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return CupertinoPageScaffold(
+      navigationBar: const CupertinoNavigationBar(
+        middle: Text('CupertinoSearchTextField Sample'),
+      ),
+      child: Center(
+        child: Padding(
+          padding: const EdgeInsets.all(16.0),
+          child: CupertinoSearchTextField(
+            controller: textController,
+            placeholder: 'Search',
+          ),
+        ),
+      ),
+    );
+  }
+}

examples/api/lib/cupertino/search_field/cupertino_search_field.1.dart

@@ -0,0 +1,80 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// Flutter code sample for CupertinoSearchTextField
+
+import 'package:flutter/cupertino.dart';
+
+void main() => runApp(const SearchTextFieldApp());
+
+class SearchTextFieldApp extends StatelessWidget {
+  const SearchTextFieldApp({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return const CupertinoApp(
+      theme: CupertinoThemeData(brightness: Brightness.light),
+      home: SearchTextFieldExample(),
+    );
+  }
+}
+
+class SearchTextFieldExample extends StatefulWidget {
+  const SearchTextFieldExample({Key? key}) : super(key: key);
+
+  @override
+  State<SearchTextFieldExample> createState() => _SearchTextFieldExampleState();
+}
+
+class _SearchTextFieldExampleState extends State<SearchTextFieldExample> {
+  String text = '';
+
+  @override
+  Widget build(BuildContext context) {
+    return CupertinoPageScaffold(
+      navigationBar: const CupertinoNavigationBar(
+        middle: Text('CupertinoSearchTextField Sample'),
+      ),
+      child: Center(
+        child: Column(
+          mainAxisAlignment: MainAxisAlignment.center,
+          children: <Widget>[
+            Text(text),
+            Padding(
+              padding: const EdgeInsets.all(16.0),
+              child: SearchTextField(
+                fieldValue: (String value) {
+                  setState(() {
+                    text = value;
+                  });
+                },
+              ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
+
+class SearchTextField extends StatelessWidget {
+  const SearchTextField({
+    Key? key,
+    required this.fieldValue,
+  }) : super(key: key);
+
+  final ValueChanged<String> fieldValue;
+
+  @override
+  Widget build(BuildContext context) {
+    return CupertinoSearchTextField(
+      onChanged: (String value) {
+        fieldValue('The text has changed to: $value');
+      },
+      onSubmitted: (String value) {
+        fieldValue('Submitted text: $value');
+      },
+    );
+  }
+}

examples/api/test/cupertino/search_field/cupertino_search_field.0_test.dart

@@ -0,0 +1,26 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/cupertino.dart';
+import 'package:flutter_api_samples/cupertino/search_field/cupertino_search_field.0.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('CupertinoTextField has initial text', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const example.SearchTextFieldApp(),
+    );
+
+    expect(find.byType(CupertinoSearchTextField), findsOneWidget);
+    expect(find.text('initial text'), findsOneWidget);
+
+    await tester.tap(find.byIcon(CupertinoIcons.xmark_circle_fill));
+    await tester.pump();
+    expect(find.text('initial text'), findsNothing);
+
+    await tester.enterText(find.byType(CupertinoSearchTextField), 'photos');
+    await tester.pump();
+    expect(find.text('photos'), findsOneWidget);
+  });
+}

examples/api/test/cupertino/search_field/cupertino_search_field.1_test.dart

@@ -0,0 +1,27 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/cupertino.dart';
+import 'package:flutter_api_samples/cupertino/search_field/cupertino_search_field.1.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('Value changed callback updates entered text', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const example.SearchTextFieldApp(),
+    );
+
+    expect(find.byType(CupertinoSearchTextField), findsOneWidget);
+
+    await tester.enterText(find.byType(CupertinoSearchTextField), 'photos');
+    await tester.pump();
+    expect(find.text('The text has changed to: photos'), findsOneWidget);
+
+    await tester.enterText(find.byType(CupertinoSearchTextField), 'photos from vacation');
+    await tester.showKeyboard(find.byType(CupertinoTextField));
+    await tester.testTextInput.receiveAction(TextInputAction.done);
+    await tester.pump();
+    expect(find.text('Submitted text: photos from vacation'), findsOneWidget);
+  });
+}

packages/flutter/lib/src/cupertino/search_field.dart

@@ -21,62 +21,24 @@ import 'text_field.dart';
 /// [controller]. For example, to set the initial value of the text field, use
 /// a [controller] that already contains some text such as:
 ///
-/// {@tool snippet}
+/// {@tool dartpad}
+/// This examples shows how to provide initial text to a [CupertinoSearchTextField]
+/// using the [controller] property.
 ///
-/// ```dart
-/// class MyPrefilledSearch extends StatefulWidget {
-///   const MyPrefilledSearch({Key? key}) : super(key: key);
-///
-///   @override
-///   State<MyPrefilledSearch> createState() => _MyPrefilledSearchState();
-/// }
-///
-/// class _MyPrefilledSearchState extends State<MyPrefilledSearch> {
-///   late TextEditingController _textController;
-///
-///   @override
-///   void initState() {
-///     super.initState();
-///     _textController = TextEditingController(text: 'initial text');
-///   }
-///
-///   @override
-///   Widget build(BuildContext context) {
-///     return CupertinoSearchTextField(controller: _textController);
-///   }
-/// }
-/// ```
+/// ** See code in examples/api/lib/cupertino/search_field/cupertino_search_field.0.dart **
 /// {@end-tool}
 ///
 /// It is recommended to pass a [ValueChanged<String>] to both [onChanged] and
 /// [onSubmitted] parameters in order to be notified once the value of the
 /// field changes or is submitted by the keyboard:
 ///
-/// {@tool snippet}
+/// {@tool dartpad}
+/// This examples shows how to be notified of field changes or submitted text from
+/// a [CupertinoSearchTextField].
 ///
-/// ```dart
-/// class MyPrefilledSearch extends StatefulWidget {
-///   const MyPrefilledSearch({Key? key}) : super(key: key);
-///
-///   @override
-///   State<MyPrefilledSearch> createState() => _MyPrefilledSearchState();
-/// }
-///
-/// class _MyPrefilledSearchState extends State<MyPrefilledSearch> {
-///   @override
-///   Widget build(BuildContext context) {
-///     return CupertinoSearchTextField(
-///       onChanged: (String value) {
-///         print('The text has changed to: $value');
-///       },
-///       onSubmitted: (String value) {
-///         print('Submitted text: $value');
-///       },
-///     );
-///   }
-/// }
-/// ```
+/// ** See code in examples/api/lib/cupertino/search_field/cupertino_search_field.1.dart **
 /// {@end-tool}
+///
 class CupertinoSearchTextField extends StatefulWidget {
   /// Creates a [CupertinoTextField] that mimics the look and behavior of
   /// UIKit's `UISearchTextField`.