[pointer_interceptor] Adopt code-excerpts for README

packages/pointer_interceptor/pointer_interceptor/CHANGELOG.md

@@ -1,5 +1,7 @@
-## NEXT
+## 0.10.1+3
 
+* Adopts `code-excerpt` for the README's Dart snippets so they are validated
+  against compilable, analyzed source.
 * Updates minimum supported SDK version to Flutter 3.38/Dart 3.10.
 * Updates README to reflect currently supported OS versions for the latest
   versions of the endorsed platform implementations.

packages/pointer_interceptor/pointer_interceptor/README.md

@@ -1,4 +1,5 @@
 # pointer_interceptor
+<?code-excerpt path-base="example/lib"?>
 
 |             | iOS     | Web |
 |-------------|---------|-----|
@@ -47,25 +48,27 @@ There's two ways that the `PointerInterceptor` widget can be used to solve the p
 
 1. Wrapping your button element directly (FAB, Custom Play/Pause button...):
 
-    ```dart
-    PointerInterceptor(
-      child: ElevatedButton(...),
-    )
-    ```
+<?code-excerpt "readme_excerpts.dart (WrapButton)"?>
+```dart
+PointerInterceptor(
+  child: ElevatedButton(
+    // ···
+  ),
+)
+```
 
 2. As a root container for a "layout" element, wrapping a bunch of other elements (like a Drawer):
 
-    ```dart
-    Scaffold(
-      ...
-      drawer: PointerInterceptor(
-        child: Drawer(
-          child: ...
-        ),
-      ),
-      ...
-    )
-    ```
+<?code-excerpt "readme_excerpts.dart (WrapSubtree)"?>
+```dart
+Scaffold(
+  drawer: PointerInterceptor(
+    child: Drawer(
+      // ···
+    ),
+  ),
+)
+```
 
 ### `intercepting`
 
@@ -76,24 +79,32 @@ The `intercepting` property allows the `PointerInterceptor` widget to render
 itself (or not) depending on a boolean value, instead of having to manually
 write an `if/else` on the Flutter App widget tree, so code like this:
 
-  ```dart
-  if (someCondition) {
-    return PointerInterceptor(
-      child: ElevatedButton(...),
-    )
-  } else {
-    return ElevatedButton(...),
-  }
-  ```
+<?code-excerpt "readme_excerpts.dart (InterceptingBefore)"?>
+```dart
+if (someCondition) {
+  return PointerInterceptor(
+    child: ElevatedButton(
+      // ···
+    ),
+  );
+} else {
+  return ElevatedButton(
+    // ···
+  );
+}
+```
 
 can be rewritten as:
 
-   ```dart
-    return PointerInterceptor(
-      intercepting: someCondition,
-      child: ElevatedButton(...),
-    )
-   ```
+<?code-excerpt "readme_excerpts.dart (InterceptingAfter)"?>
+```dart
+PointerInterceptor(
+  intercepting: someCondition,
+  child: ElevatedButton(
+    // ···
+  ),
+)
+```
 
 Note: when `intercepting` is false, the `PointerInterceptor` will not render
 _anything_ in flutter, and just return its `child`. The code is exactly

packages/pointer_interceptor/pointer_interceptor/example/lib/readme_excerpts.dart

@@ -0,0 +1,82 @@
+// Copyright 2013 The Flutter Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/material.dart';
+import 'package:pointer_interceptor/pointer_interceptor.dart';
+
+/// Wraps a single button so that it can be clicked, even when it's on top of
+/// a platform view.
+Widget wrapButtonSnippet() {
+  return
+  // #docregion WrapButton
+  PointerInterceptor(
+    child: ElevatedButton(
+      // #enddocregion WrapButton
+      onPressed: () {},
+      child: const Text('Button'),
+      // #docregion WrapButton
+    ),
+  )
+  // #enddocregion WrapButton
+  ;
+}
+
+/// Wraps a whole subtree (a [Drawer], in this case) so that it can be
+/// clicked, even when it's on top of a platform view.
+Widget wrapSubtreeSnippet() {
+  return
+  // #docregion WrapSubtree
+  Scaffold(
+    drawer: PointerInterceptor(
+      child: Drawer(
+        // #enddocregion WrapSubtree
+        child: ListView(children: const <Widget>[Text('Drawer contents')]),
+        // #docregion WrapSubtree
+      ),
+    ),
+  )
+  // #enddocregion WrapSubtree
+  ;
+}
+
+/// The naive way of conditionally intercepting pointer events, which
+/// `intercepting` is meant to replace.
+Widget interceptingBeforeSnippet(bool someCondition) {
+  // #docregion InterceptingBefore
+  if (someCondition) {
+    return PointerInterceptor(
+      child: ElevatedButton(
+        // #enddocregion InterceptingBefore
+        onPressed: () {},
+        child: const Text('Button'),
+        // #docregion InterceptingBefore
+      ),
+    );
+  } else {
+    return ElevatedButton(
+      // #enddocregion InterceptingBefore
+      onPressed: () {},
+      child: const Text('Button'),
+      // #docregion InterceptingBefore
+    );
+  }
+  // #enddocregion InterceptingBefore
+}
+
+/// The equivalent of [interceptingBeforeSnippet], using `intercepting`.
+Widget interceptingAfterSnippet(bool someCondition) {
+  return
+  // #docregion InterceptingAfter
+  PointerInterceptor(
+    intercepting: someCondition,
+    child: ElevatedButton(
+      // #enddocregion InterceptingAfter
+      onPressed: () {},
+      child: const Text('Button'),
+      // #docregion InterceptingAfter
+    ),
+  )
+  // #enddocregion InterceptingAfter
+  ;
+}

packages/pointer_interceptor/pointer_interceptor/example/test/readme_excerpts_test.dart

@@ -0,0 +1,58 @@
+// Copyright 2013 The Flutter Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pointer_interceptor/pointer_interceptor.dart';
+import 'package:pointer_interceptor_example/readme_excerpts.dart';
+
+void main() {
+  testWidgets('wrapButtonSnippet wraps a button in a PointerInterceptor', (
+    WidgetTester tester,
+  ) async {
+    await tester.pumpWidget(MaterialApp(home: wrapButtonSnippet()));
+
+    expect(find.byType(PointerInterceptor), findsOneWidget);
+    expect(find.widgetWithText(ElevatedButton, 'Button'), findsOneWidget);
+  });
+
+  testWidgets('wrapSubtreeSnippet wraps a Drawer in a PointerInterceptor', (
+    WidgetTester tester,
+  ) async {
+    await tester.pumpWidget(MaterialApp(home: wrapSubtreeSnippet()));
+    tester.state<ScaffoldState>(find.byType(Scaffold)).openDrawer();
+    await tester.pumpAndSettle();
+
+    expect(find.byType(PointerInterceptor), findsOneWidget);
+    expect(find.widgetWithText(Drawer, 'Drawer contents'), findsOneWidget);
+  });
+
+  testWidgets('interceptingBeforeSnippet returns a PointerInterceptor when true', (
+    WidgetTester tester,
+  ) async {
+    await tester.pumpWidget(MaterialApp(home: interceptingBeforeSnippet(true)));
+
+    expect(find.byType(PointerInterceptor), findsOneWidget);
+    expect(find.widgetWithText(ElevatedButton, 'Button'), findsOneWidget);
+  });
+
+  testWidgets('interceptingBeforeSnippet returns a plain button when false', (
+    WidgetTester tester,
+  ) async {
+    await tester.pumpWidget(MaterialApp(home: interceptingBeforeSnippet(false)));
+
+    expect(find.byType(PointerInterceptor), findsNothing);
+    expect(find.widgetWithText(ElevatedButton, 'Button'), findsOneWidget);
+  });
+
+  testWidgets('interceptingAfterSnippet sets intercepting from its argument', (
+    WidgetTester tester,
+  ) async {
+    await tester.pumpWidget(MaterialApp(home: interceptingAfterSnippet(true)));
+
+    final PointerInterceptor interceptor = tester.widget(find.byType(PointerInterceptor));
+    expect(interceptor.intercepting, isTrue);
+    expect(find.widgetWithText(ElevatedButton, 'Button'), findsOneWidget);
+  });
+}

packages/pointer_interceptor/pointer_interceptor/pubspec.yaml

@@ -2,7 +2,7 @@ name: pointer_interceptor
 description: A widget to prevent clicks from being swallowed by underlying HtmlElementViews on the web.
 repository: https://github.com/flutter/packages/tree/main/packages/pointer_interceptor/pointer_interceptor
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+pointer_interceptor%22
-version: 0.10.1+2
+version: 0.10.1+3
 
 environment:
   sdk: ^3.10.0