feat: Add file chooser support for widget preview initialization. (#8888)

When using a multi-module project, the widget previewer sometimes fails
to automatically find the correct pubspec.yaml. Adding the possibility
to manually choose the file allows for more complex project setups.

<img width="462" height="614" alt="Screenshot 2026-04-03 at 22 46 57"
src="https://github.com/user-attachments/assets/c0554589-aa4b-4077-b293-f3261db9f6af"
/>

<img width="882" height="451" alt="Screenshot 2026-04-16 at 16 12 18"
src="https://github.com/user-attachments/assets/3b41e615-0b04-45cf-a78e-0450b056a654"
/>

---

Review the contribution guidelines below:

- [x] I’ve reviewed the contributor guide and applied the relevant
portions to this PR.
- [x] I've included the required information in the description above.
- [x] My up-to-date information is in the `AUTHORS` file.
- [x] I've updated `CHANGELOG.md` if appropriate.

<details>
  <summary>Contribution guidelines:</summary><br>

- See
  our [contributor guide](../CONTRIBUTING.md) and
the [Flutter organization contributor
guide]([https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md)
  for general expectations for PRs.
- Larger or significant changes should be discussed in an issue before
creating a PR.
- Dart contributions to our repos should follow the [Dart style
guide](https://dart.dev/guides/language/effective-dart) and use
  `dart format`.
- Java and Kotlin contributions should strive to follow Java and Kotlin
best
practices
([discussion](#8098)).

</details>

Author: nopjar

AUTHORS

@@ -27,3 +27,4 @@ Edwin Ludik <edwin.ludik@gmail.com>
 Japnit Singh <truejswalia@gmail.com>
 Dmitry Kandalov <dmitry.kandalov@gmail.com>
 Kazuya Chikamatsu <kazu.chika.shima@gmail.com>
+Dustin Feucht <code.nopjar@gmail.com>

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ### Added
 
+- Option to specify the pub root module for Flutter Widget Previewer. (#8888)
+
 ### Changed
 
 ### Removed

src/io/flutter/FlutterBundle.properties

@@ -193,4 +193,9 @@ widget.preview.starting=Starting Flutter Widget Preview web server...
 widget.preview.loading=Loading Flutter Widget Preview at {0}...
 widget.preview.error=Error: {0}
 widget.preview.sdk.too.old=Flutter SDK version is too old for Flutter Widget Preview. Please update your SDK.
+widget.preview.pubroot.not.found=Pub root could not be found to start Flutter Widget Preview.
+widget.preview.retry=Reload and try again
+widget.preview.choose_pubroot=Choose module and try again
+widget.preview.choose_pubroot.title=Select Flutter Project
+widget.preview.choose_pubroot.description=Select the Flutter project to use for Flutter Widget Preview.
 flutter.sdk.not.found=Flutter SDK not found.

src/io/flutter/widgetpreview/WidgetPreviewPanel.java

@@ -8,9 +8,14 @@
 import com.intellij.openapi.diagnostic.Logger;
 import com.intellij.openapi.editor.colors.EditorColorsListener;
 import com.intellij.openapi.editor.colors.EditorColorsManager;
+import com.intellij.openapi.fileChooser.FileChooserDescriptor;
+import com.intellij.openapi.fileChooser.FileChooserDescriptorFactory;
+import com.intellij.openapi.fileChooser.FileChooser;
 import com.intellij.openapi.project.Project;
+import com.intellij.openapi.roots.ProjectFileIndex;
 import com.intellij.openapi.ui.SimpleToolWindowPanel;
 import com.intellij.openapi.util.Disposer;
+import com.intellij.openapi.vfs.VirtualFile;
 import com.intellij.openapi.wm.ToolWindow;
 import com.intellij.util.messages.MessageBusConnection;
 import com.jetbrains.lang.dart.ide.toolingDaemon.DartToolingDaemonService;
@@ -22,12 +27,14 @@
 import io.flutter.devtools.DevToolsUtils;
 import io.flutter.logging.PluginLogger;
 import io.flutter.pub.PubRoot;
+import io.flutter.pub.PubRootCache;
 import io.flutter.run.daemon.DevToolsInstance;
 import io.flutter.run.daemon.DevToolsService;
 import io.flutter.sdk.FlutterCommand;
 import io.flutter.sdk.FlutterSdk;
 import io.flutter.sdk.FlutterSdkVersion;
 import io.flutter.settings.FlutterSettings;
+import io.flutter.utils.LabelInput;
 import io.flutter.utils.MostlySilentColoredProcessHandler;
 import io.flutter.utils.OpenApiUtils;
 import io.flutter.view.BrowserUrlProvider;
@@ -71,10 +78,10 @@ public WidgetPreviewPanel(@NotNull Project project, @NotNull ToolWindow toolWind
     showInfoMessage(FlutterBundle.message("widget.preview.initializing"));
 
     // Start the preview process asynchronously
-    startWidgetPreview();
+    startWidgetPreview(null);
   }
 
-  private void startWidgetPreview() {
+  private void startWidgetPreview(@Nullable VirtualFile file) {
     OpenApiUtils.safeExecuteOnPooledThread(() -> {
       try {
         // Check versioning of Flutter SDK.
@@ -125,10 +132,10 @@ private void startWidgetPreview() {
           });
         });
 
-        final PubRoot root = PubRoot.forFile(project.getProjectFile());
+        final PubRoot root = getPubRoot(file);
         if (root == null) {
           LOG.warn("Pub root not found for project: " + project.getName());
-          showInfoMessage("Pub root could not be found to start widget preview.");
+          showRetryMessage(FlutterBundle.message("widget.preview.pubroot.not.found"), file);
           return;
         }
 
@@ -150,6 +157,16 @@ private void startWidgetPreview() {
     });
   }
 
+  private @Nullable PubRoot getPubRoot(@Nullable VirtualFile file) {
+    return OpenApiUtils.safeRunReadAction(() -> {
+      if (file != null) {
+        return PubRootCache.getInstance(project).getRoot(file);
+      } else {
+        return PubRoot.forFile(project.getProjectFile());
+      }
+    });
+  }
+
   private @Nullable String getDevToolsUri() {
     try {
       final CompletableFuture<DevToolsInstance> devToolsFuture = DevToolsService.getInstance(project).getDevToolsInstance();
@@ -252,6 +269,34 @@ private void showInfoMessage(@NotNull String message) {
     });
   }
 
+  private void showRetryMessage(@NotNull String message, @Nullable VirtualFile file) {
+    ApplicationManager.getApplication().invokeLater(() -> {
+      final List<LabelInput> inputs = List.of(
+        new LabelInput(message),
+        new LabelInput(FlutterBundle.message("widget.preview.retry"), (label, data) -> startWidgetPreview(file)),
+        new LabelInput(FlutterBundle.message("widget.preview.choose_pubroot"), (label, data) -> chooseFile())
+      );
+      final JPanel panel = viewUtils.createClickableLabelPanel(inputs);
+      contentPanel.removeAll();
+      contentPanel.add(panel, BorderLayout.CENTER);
+      contentPanel.revalidate();
+      contentPanel.repaint();
+    });
+  }
+
+  private void chooseFile() {
+    final FileChooserDescriptor descriptor = FileChooserDescriptorFactory.singleFileOrDir()
+      .withTitle(FlutterBundle.message("widget.preview.choose_pubroot.title"))
+      .withDescription(FlutterBundle.message("widget.preview.choose_pubroot.description"))
+      .withRoots(FlutterUtils.getProjectRoot(project));
+
+    final VirtualFile selectedFile = FileChooser.chooseFile(descriptor, project, null);
+    if (selectedFile != null
+        && OpenApiUtils.safeRunReadAction(() -> ProjectFileIndex.getInstance(project).isInContent(selectedFile))) {
+      startWidgetPreview(selectedFile);
+    }
+  }
+
   @Override
   public void dispose() {
     // Terminate the Flutter process when the tool window is closed