diff --git a/packages/pointer_interceptor/pointer_interceptor/CHANGELOG.md b/packages/pointer_interceptor/pointer_interceptor/CHANGELOG.md index d7aa50de475b..401bd88ecd84 100644 --- a/packages/pointer_interceptor/pointer_interceptor/CHANGELOG.md +++ b/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. diff --git a/packages/pointer_interceptor/pointer_interceptor/README.md b/packages/pointer_interceptor/pointer_interceptor/README.md index 2e5c3bfcc09f..bb7394a5d803 100644 --- a/packages/pointer_interceptor/pointer_interceptor/README.md +++ b/packages/pointer_interceptor/pointer_interceptor/README.md @@ -1,4 +1,5 @@ # pointer_interceptor + | | 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(...), - ) - ``` + +```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: ... - ), - ), - ... - ) - ``` + +```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(...), - } - ``` + +```dart +if (someCondition) { + return PointerInterceptor( + child: ElevatedButton( + // ··· + ), + ); +} else { + return ElevatedButton( + // ··· + ); +} +``` can be rewritten as: - ```dart - return PointerInterceptor( - intercepting: someCondition, - child: ElevatedButton(...), - ) - ``` + +```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 diff --git a/packages/pointer_interceptor/pointer_interceptor/ci_config.yaml b/packages/pointer_interceptor/pointer_interceptor/ci_config.yaml deleted file mode 100644 index b352e13e0dfa..000000000000 --- a/packages/pointer_interceptor/pointer_interceptor/ci_config.yaml +++ /dev/null @@ -1,2 +0,0 @@ -# TODO(stuartmorgan): Remove this; see https://github.com/flutter/flutter/issues/102679 -exempt_from_excerpts: true diff --git a/packages/pointer_interceptor/pointer_interceptor/example/lib/readme_excerpts.dart b/packages/pointer_interceptor/pointer_interceptor/example/lib/readme_excerpts.dart new file mode 100644 index 000000000000..3c400e94421f --- /dev/null +++ b/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 [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 + ; +} diff --git a/packages/pointer_interceptor/pointer_interceptor/example/test/readme_excerpts_test.dart b/packages/pointer_interceptor/pointer_interceptor/example/test/readme_excerpts_test.dart new file mode 100644 index 000000000000..7306e58e2b27 --- /dev/null +++ b/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(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); + }); +} diff --git a/packages/pointer_interceptor/pointer_interceptor/pubspec.yaml b/packages/pointer_interceptor/pointer_interceptor/pubspec.yaml index 259101e6f7e1..5a0495132567 100644 --- a/packages/pointer_interceptor/pointer_interceptor/pubspec.yaml +++ b/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