[ Widget Preview ] Respond to IDE navigation events and show previews from the currently focused script (flutter#174466)

This change allows for the widget previewer to react to
`activeLocationChanged` events sent over the `Editor` DTD service to
automatically filter the set of visible previews based on the currently
selected file in the IDE. This functionality can be turned on or off
depending on whether or not the developer wants to see all previews in
the project at once.

This change also includes some minor refactoring and UI changes to move
the widget preview environment controls to a reserved area at the bottom
of the preview window.

**Demo:**


https://github.com/user-attachments/assets/c3b93826-8437-4655-8264-6beed6651fe7

Author: bkonyi

packages/flutter_tools/lib/src/widget_preview/dependency_graph.dart

@@ -35,7 +35,8 @@ typedef PreviewDependencyGraph = Map<PreviewPath, LibraryPreviewNode>;
 class _PreviewVisitor extends RecursiveAstVisitor<void> {
   _PreviewVisitor({required LibraryElement2 lib})
     : packageName = lib.uri.scheme == 'package' ? lib.uri.pathSegments.first : null,
-      _context = lib.session.analysisContext;
+      _context = lib.session.analysisContext,
+      _currentScriptUri = null;
 
   late final String? packageName;
 
@@ -46,6 +47,12 @@ class _PreviewVisitor extends RecursiveAstVisitor<void> {
   ConstructorDeclaration? _currentConstructor;
   MethodDeclaration? _currentMethod;
 
+  Uri? _currentScriptUri;
+
+  void findPreviewsInResolvedUnitResult(ResolvedUnitResult unit) {
+    _scopedVisitChildren(unit.unit, (_) => _currentScriptUri = unit.file.toUri());
+  }
+
   /// Handles previews defined on top-level functions.
   @override
   void visitFunctionDeclaration(FunctionDeclaration node) {
@@ -104,6 +111,7 @@ class _PreviewVisitor extends RecursiveAstVisitor<void> {
           if (returnType.isWidget || returnType.isWidgetBuilder) {
             previewEntries.add(
               PreviewDetails(
+                scriptUri: _currentScriptUri!,
                 packageName: packageName,
                 functionName: _currentFunction!.name.toString(),
                 isBuilder: returnType.isWidgetBuilder,
@@ -118,6 +126,7 @@ class _PreviewVisitor extends RecursiveAstVisitor<void> {
         final Token? name = _currentConstructor!.name;
         previewEntries.add(
           PreviewDetails(
+            scriptUri: _currentScriptUri!,
             packageName: packageName,
             functionName: '$returnType${name == null ? '' : '.$name'}',
             isBuilder: false,
@@ -132,6 +141,7 @@ class _PreviewVisitor extends RecursiveAstVisitor<void> {
             final parentClass = _currentMethod!.parent! as ClassDeclaration;
             previewEntries.add(
               PreviewDetails(
+                scriptUri: _currentScriptUri!,
                 packageName: packageName,
                 functionName: '${parentClass.name}.${_currentMethod!.name}',
                 isBuilder: returnType.isWidgetBuilder,
@@ -210,9 +220,7 @@ final class LibraryPreviewNode {
   void findPreviews({required ResolvedLibraryResult lib}) {
     // Iterate over the compilation unit's AST to find previews.
     final visitor = _PreviewVisitor(lib: lib.element);
-    for (final ResolvedUnitResult libUnit in lib.units) {
-      libUnit.unit.visitChildren(visitor);
-    }
+    lib.units.forEach(visitor.findPreviewsInResolvedUnitResult);
     previews
       ..clear()
       ..addAll(visitor.previewEntries);

packages/flutter_tools/lib/src/widget_preview/preview_code_generator.dart

@@ -190,6 +190,7 @@ class PreviewCodeGenerator {
     return cb.refer(_kWidgetPreviewClass, _kWidgetPreviewLibraryUri).newInstance(
       <cb.Expression>[],
       <String, cb.Expression>{
+        PreviewDetails.kScriptUri: cb.literalString(preview.scriptUri.toString()),
         // TODO(bkonyi): try to display the preview name, even if the preview can't be displayed.
         if (!libraryDetails.dependencyHasErrors &&
             !libraryDetails.hasErrors) ...<String, cb.Expression>{

packages/flutter_tools/lib/src/widget_preview/preview_details.dart

@@ -7,6 +7,7 @@ import 'package:analyzer/dart/constant/value.dart';
 /// Contains details related to a single preview instance.
 final class PreviewDetails {
   PreviewDetails({
+    required this.scriptUri,
     required this.packageName,
     required this.functionName,
     required this.isBuilder,
@@ -19,6 +20,7 @@ final class PreviewDetails {
        brightness = previewAnnotation.getField(kBrightness)!,
        localizations = previewAnnotation.getField(kLocalizations)!;
 
+  static const kScriptUri = 'scriptUri';
   static const kPackageName = 'packageName';
   static const kName = 'name';
   static const kSize = 'size';
@@ -28,6 +30,9 @@ final class PreviewDetails {
   static const kBrightness = 'brightness';
   static const kLocalizations = 'localizations';
 
+  /// The file:// URI pointing to the script in which the preview is defined.
+  final Uri scriptUri;
+
   /// The name of the package in which the preview was defined.
   ///
   /// For example, if this preview is defined in 'package:foo/src/bar.dart', this

packages/flutter_tools/templates/template_manifest.json

@@ -348,6 +348,7 @@
     "templates/widget_preview_scaffold/lib/main.dart.tmpl",
     "templates/widget_preview_scaffold/lib/src/widget_preview.dart.tmpl",
     "templates/widget_preview_scaffold/lib/src/widget_preview_rendering.dart.tmpl",
+    "templates/widget_preview_scaffold/lib/src/widget_preview_scaffold_controller.dart.tmpl",
     "templates/widget_preview_scaffold/lib/src/controls.dart.tmpl",
     "templates/widget_preview_scaffold/lib/src/dtd/dtd_services.dart.tmpl",
     "templates/widget_preview_scaffold/lib/src/dtd/editor_service.dart.tmpl",

packages/flutter_tools/templates/widget_preview_scaffold/lib/src/controls.dart.tmpl

@@ -3,7 +3,7 @@
 // found in the LICENSE file.
 
 import 'package:flutter/material.dart';
-import 'package:widget_preview_scaffold/src/dtd/dtd_services.dart';
+import 'widget_preview_scaffold_controller.dart';
 
 class _WidgetPreviewIconButton extends StatelessWidget {
   const _WidgetPreviewIconButton({
@@ -97,6 +97,85 @@ class ZoomControls extends StatelessWidget {
   }
 }
 
+class _ControlDecorator extends StatelessWidget {
+  const _ControlDecorator({required this.child});
+
+  final Widget child;
+
+  @override
+  Widget build(BuildContext context) {
+    return Container(
+      padding: EdgeInsets.all(8.0),
+      decoration: BoxDecoration(
+        color: Colors.grey[300],
+        borderRadius: BorderRadius.circular(8.0),
+      ),
+      child: child,
+    );
+  }
+}
+
+/// Allows for controlling the grid vs layout view in the preview environment.
+class LayoutTypeSelector extends StatelessWidget {
+  const LayoutTypeSelector({super.key, required this.controller});
+
+  final WidgetPreviewScaffoldController controller;
+
+  @override
+  Widget build(BuildContext context) {
+    return _ControlDecorator(
+      child: ValueListenableBuilder<LayoutType>(
+        valueListenable: controller.layoutTypeListenable,
+        builder: (context, selectedLayout, _) {
+          return Row(
+            children: [
+              IconButton(
+                onPressed: () => controller.layoutType = LayoutType.gridView,
+                icon: Icon(Icons.grid_on),
+                color: selectedLayout == LayoutType.gridView
+                    ? Colors.blue
+                    : Colors.black,
+              ),
+              IconButton(
+                onPressed: () => controller.layoutType = LayoutType.listView,
+                icon: Icon(Icons.view_list),
+                color: selectedLayout == LayoutType.listView
+                    ? Colors.blue
+                    : Colors.black,
+              ),
+            ],
+          );
+        },
+      ),
+    );
+  }
+}
+
+/// A toggle button that enables / disables filtering previews by the currently
+/// selected source file.
+class FilterBySelectedFileToggle extends StatelessWidget {
+  const FilterBySelectedFileToggle({super.key, required this.controller});
+
+  final WidgetPreviewScaffoldController controller;
+
+  @override
+  Widget build(BuildContext context) {
+    return _ControlDecorator(
+      child: ValueListenableBuilder(
+        valueListenable: controller.filterBySelectedFileListenable,
+        builder: (context, value, child) {
+          return IconButton(
+            onPressed: controller.toggleFilterBySelectedFile,
+            icon: Icon(Icons.file_open),
+            color: value ? Colors.blue : Colors.black,
+            tooltip: 'Filter previews by selected file',
+          );
+        },
+      ),
+    );
+  }
+}
+
 /// A button that triggers a "soft" restart of a previewed widget.
 ///
 /// A soft restart removes the previewed widget from the widget tree for a frame before
@@ -129,16 +208,18 @@ class SoftRestartButton extends StatelessWidget {
 /// A button that triggers a restart of the widget previewer through a hot restart request made
 /// through DTD.
 class WidgetPreviewerRestartButton extends StatelessWidget {
-  const WidgetPreviewerRestartButton({super.key, required this.dtdServices});
+  const WidgetPreviewerRestartButton({super.key, required this.controller});
 
-  final WidgetPreviewScaffoldDtdServices dtdServices;
+  final WidgetPreviewScaffoldController controller;
 
   @override
   Widget build(BuildContext context) {
-    return IconButton.outlined(
-      tooltip: 'Restart the Widget Previewer',
-      onPressed: () => dtdServices.hotRestartPreviewer(),
-      icon: Icon(Icons.restart_alt),
+    return _ControlDecorator(
+      child: IconButton(
+        tooltip: 'Restart the Widget Previewer',
+        onPressed: controller.dtdServices.hotRestartPreviewer,
+        icon: Icon(Icons.restart_alt),
+      ),
     );
   }
 }

packages/flutter_tools/templates/widget_preview_scaffold/lib/src/dtd/dtd_services.dart.tmpl

@@ -5,7 +5,7 @@
 import 'dart:async';
 
 import 'package:dtd/dtd.dart';
-import 'package:widget_preview_scaffold/src/dtd/editor_service.dart';
+import 'editor_service.dart';
 
 /// Provides services, streams, and RPC invocations to interact with Flutter developer tooling.
 class WidgetPreviewScaffoldDtdServices with DtdEditorService {
@@ -42,6 +42,13 @@ class WidgetPreviewScaffoldDtdServices with DtdEditorService {
     await initializeEditorService();
   }
 
+  /// Disposes the DTD connection.
+  @override
+  Future<void> dispose() async {
+    super.dispose();
+    await dtd.close();
+  }
+
   Future<DTDResponse> _call(
     String methodName, {
     Map<String, Object?>? params,

packages/flutter_tools/templates/widget_preview_scaffold/lib/src/dtd/editor_service.dart.tmpl

@@ -40,6 +40,12 @@ mixin DtdEditorService {
     });
     await dtd.streamListen(kEditorService);
   }
+
+  @mustCallSuper
+  void dispose() {
+    _selectedSourceFile.dispose();
+    _editorTheme.dispose();
+  }
 }
 
 // TODO(bkonyi): much of the following code is copied from the DevTools codebase. We should publish

packages/flutter_tools/templates/widget_preview_scaffold/lib/src/utils.dart.tmpl

@@ -31,3 +31,44 @@ class VerticalSpacer extends StatelessWidget {
     return const SizedBox(height: 10);
   }
 }
+
+/// A basic horizontal spacer.
+class HorizontalSpacer extends StatelessWidget {
+  /// Creates a basic vertical spacer.
+  const HorizontalSpacer({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return const SizedBox(width: 10);
+  }
+}
+
+/// A widget that explicitly responds to hot reload events.
+///
+/// Hot reload will always result in [reassemble] being called.
+class HotReloadListener extends StatefulWidget {
+  const HotReloadListener({
+    super.key,
+    required this.onHotReload,
+    required this.child,
+  });
+
+  final VoidCallback onHotReload;
+  final Widget child;
+
+  @override
+  HotReloadListenerState createState() => HotReloadListenerState();
+}
+
+class HotReloadListenerState extends State<HotReloadListener> {
+  @override
+  void reassemble() {
+    super.reassemble();
+    widget.onHotReload();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return widget.child;
+  }
+}

packages/flutter_tools/templates/widget_preview_scaffold/lib/src/widget_preview.dart.tmpl

@@ -8,19 +8,12 @@ import 'package:flutter/widgets.dart';
 
 /// Wraps a [Widget], initializing various state and properties to allow for
 /// previewing of the [Widget] in the widget previewer.
-///
-/// WARNING: This interface is not stable and **will change**.
-///
-/// See also:
-///
-///  * [Preview], an annotation class used to mark functions returning widget
-///    previews.
-// TODO(bkonyi): link to actual documentation when available.
 class WidgetPreview {
   /// Wraps [builder] in a [WidgetPreview] instance that applies some set of
   /// properties.
   const WidgetPreview({
     required this.builder,
+    required this.scriptUri,
     this.packageName,
     this.name,
     this.size,
@@ -30,6 +23,11 @@ class WidgetPreview {
     this.localizations,
   });
 
+  /// The absolute file:// URI pointing to the script containing this preview.
+  ///
+  /// This matches the URI format sent by IDEs for active location change events.
+  final String scriptUri;
+
   /// The name of the package in which a preview was defined.
   ///
   /// For example, if a preview is defined in 'package:foo/src/bar.dart', this