Implementation of walkthrough infrastructure

jabgui/src/main/java/org/jabref/gui/JabRefGUI.java

@@ -75,7 +75,6 @@ public class JabRefGUI extends Application {
     private static ClipBoardManager clipBoardManager;
     private static DialogService dialogService;
     private static JabRefFrame mainFrame;
-
     private static RemoteListenerServerManager remoteListenerServerManager;
 
     private Stage mainStage;
@@ -191,7 +190,7 @@ public void initialize() {
 
     private void setupProxy() {
         if (!preferences.getProxyPreferences().shouldUseProxy()
-                || !preferences.getProxyPreferences().shouldUseAuthentication()) {
+            || !preferences.getProxyPreferences().shouldUseAuthentication()) {
             return;
         }
 

jabgui/src/main/java/org/jabref/gui/actions/StandardActions.java

@@ -184,6 +184,9 @@ public enum StandardActions implements Action {
     OPEN_DEV_VERSION_LINK(Localization.lang("Development version"), Localization.lang("Opens a link where the current development version can be downloaded")),
     OPEN_CHANGELOG(Localization.lang("View change log"), Localization.lang("See what has been changed in the JabRef versions")),
     OPEN_GITHUB("GitHub", Localization.lang("Opens JabRef's GitHub page"), IconTheme.JabRefIcons.GITHUB),
+    WALKTHROUGH_MENU(Localization.lang("Walkthroughs")),
+    MAIN_FILE_DIRECTORY_WALKTHROUGH(Localization.lang("Configure Main File Directory"), IconTheme.JabRefIcons.LATEX_FILE_DIRECTORY),
+    EDIT_ENTRY_WALKTHROUGH(Localization.lang("Edit entry"), IconTheme.JabRefIcons.EDIT_ENTRY),
     DONATE(Localization.lang("Donate to JabRef"), Localization.lang("Donate to JabRef"), IconTheme.JabRefIcons.DONATE),
     OPEN_FORUM(Localization.lang("Community forum"), Localization.lang("Community forum"), IconTheme.JabRefIcons.FORUM),
     ERROR_CONSOLE(Localization.lang("View event log"), Localization.lang("Display all error messages")),

jabgui/src/main/java/org/jabref/gui/frame/JabRefFrame.java

@@ -521,9 +521,9 @@ public void showWelcomeTab() {
     }
 
     /**
-     * Opens a new tab with existing data.
-     * Asynchronous loading is done at {@link LibraryTab#createLibraryTab}.
-     * Similar method: {@link OpenDatabaseAction#openTheFile(Path)}
+     * Opens a new tab with existing data. Asynchronous loading is done at
+     * {@link LibraryTab#createLibraryTab}. Similar method:
+     * {@link OpenDatabaseAction#openTheFile(Path)}
      */
     public void addTab(@NonNull BibDatabaseContext databaseContext, boolean raisePanel) {
         Objects.requireNonNull(databaseContext);
@@ -681,7 +681,8 @@ public CloseDatabaseAction(LibraryTabContainer tabContainer, LibraryTab libraryT
         }
 
         /**
-         * Using this constructor will result in executing the command on the currently open library tab
+         * Using this constructor will result in executing the command on the currently
+         * open library tab
          */
         public CloseDatabaseAction(LibraryTabContainer tabContainer, StateManager stateManager) {
             this(tabContainer, null, stateManager);

jabgui/src/main/java/org/jabref/gui/frame/MainMenu.java

@@ -75,6 +75,7 @@
 import org.jabref.gui.undo.UndoAction;
 import org.jabref.gui.util.URLs;
 import org.jabref.gui.util.UiTaskExecutor;
+import org.jabref.gui.walkthrough.WalkthroughAction;
 import org.jabref.logic.ai.AiService;
 import org.jabref.logic.citationstyle.CitationStyleOutputFormat;
 import org.jabref.logic.help.HelpFile;
@@ -374,6 +375,10 @@ private void createMenu() {
                         factory.createMenuItem(StandardActions.OPEN_DEV_VERSION_LINK, new OpenBrowserAction(URLs.DEV_VERSION_LINK_URL, dialogService, preferences.getExternalApplicationsPreferences())),
                         factory.createMenuItem(StandardActions.OPEN_CHANGELOG, new OpenBrowserAction(URLs.CHANGELOG_URL, dialogService, preferences.getExternalApplicationsPreferences()))
                 ),
+                factory.createSubMenu(StandardActions.WALKTHROUGH_MENU,
+                        factory.createMenuItem(StandardActions.MAIN_FILE_DIRECTORY_WALKTHROUGH, new WalkthroughAction("mainFileDirectory", frame)),
+                        factory.createMenuItem(StandardActions.EDIT_ENTRY_WALKTHROUGH, new WalkthroughAction("editEntry", frame))
+                ),
 
                 factory.createMenuItem(StandardActions.OPEN_WELCOME_TAB, new SimpleCommand() {
                     @Override

jabgui/src/main/java/org/jabref/gui/preferences/PreferencesDialogView.java

@@ -1,4 +1,4 @@
-package org.jabref.gui.preferences;
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                 package org.jabref.gui.preferences;
 
 import java.util.Locale;
 import java.util.Optional;

jabgui/src/main/java/org/jabref/gui/walkthrough/HighlightManager.java

@@ -0,0 +1,131 @@
+package org.jabref.gui.walkthrough;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+
+import javafx.scene.Node;
+import javafx.scene.Scene;
+import javafx.scene.layout.Pane;
+import javafx.stage.Window;
+
+import org.jabref.gui.walkthrough.components.BackdropHighlight;
+import org.jabref.gui.walkthrough.components.FullScreenDarken;
+import org.jabref.gui.walkthrough.components.PulseAnimateIndicator;
+import org.jabref.gui.walkthrough.declarative.effect.HighlightEffect;
+import org.jabref.gui.walkthrough.declarative.effect.MultiWindowHighlight;
+
+import org.jspecify.annotations.NonNull;
+
+/**
+ * Manages highlight effects across multiple windows for walkthrough steps.
+ */
+public class HighlightManager {
+    private final Map<Window, BackdropHighlight> backdropHighlights = new HashMap<>();
+    private final Map<Window, PulseAnimateIndicator> pulseIndicators = new HashMap<>();
+    private final Map<Window, FullScreenDarken> fullScreenDarkens = new HashMap<>();
+
+    /**
+     * Applies the specified highlight configuration.
+     *
+     * @param mainScene       The primary scene to apply the highlight to.
+     * @param highlightConfig The optional highlight configuration to apply. Default to
+     *                        BackdropHighlight on the primary windows if empty.
+     * @param fallbackTarget  The optional fallback target node to use if no highlight
+     *                        configuration is provided.
+     */
+    public void applyHighlight(@NonNull Scene mainScene,
+                               Optional<MultiWindowHighlight> highlightConfig,
+                               Optional<Node> fallbackTarget) {
+        detachAll();
+
+        highlightConfig.ifPresentOrElse(
+                config -> {
+                    if (config.windowEffects().isEmpty() && config.fallbackEffect().isPresent()) {
+                        applyEffect(mainScene.getWindow(), config.fallbackEffect().get(), fallbackTarget);
+                        return;
+                    }
+                    config.windowEffects().forEach(effect -> {
+                        Window window = effect.windowResolver().resolve().orElse(mainScene.getWindow());
+                        Optional<Node> targetNode = effect.targetNodeResolver()
+                                                          .map(resolver ->
+                                                                  resolver.resolve(Optional.ofNullable(window.getScene()).orElse(mainScene)))
+                                                          .orElse(fallbackTarget);
+                        applyEffect(window, effect.effect(), targetNode);
+                    });
+                },
+                () -> fallbackTarget.ifPresent(node -> applyBackdropHighlight(mainScene.getWindow(), node))
+        );
+    }
+
+    /**
+     * Detaches all active highlight effects.
+     */
+    public void detachAll() {
+        backdropHighlights.values().forEach(BackdropHighlight::detach);
+        backdropHighlights.clear();
+
+        pulseIndicators.values().forEach(PulseAnimateIndicator::detach);
+        pulseIndicators.clear();
+
+        fullScreenDarkens.values().forEach(FullScreenDarken::detach);
+        fullScreenDarkens.clear();
+    }
+
+    private void applyEffect(Window window, HighlightEffect effect, Optional<Node> targetNode) {
+        switch (effect) {
+            case BACKDROP_HIGHLIGHT ->
+                    targetNode.ifPresent(node -> applyBackdropHighlight(window, node));
+            case ANIMATED_PULSE ->
+                    targetNode.ifPresent(node -> applyPulseAnimation(window, node));
+            case FULL_SCREEN_DARKEN -> applyFullScreenDarken(window);
+            case NONE -> {
+                if (backdropHighlights.containsKey(window)) {
+                    backdropHighlights.get(window).detach();
+                    backdropHighlights.remove(window);
+                }
+                if (pulseIndicators.containsKey(window)) {
+                    pulseIndicators.get(window).detach();
+                    pulseIndicators.remove(window);
+                }
+                if (fullScreenDarkens.containsKey(window)) {
+                    fullScreenDarkens.get(window).detach();
+                    fullScreenDarkens.remove(window);
+                }
+            }
+        }
+    }
+
+    private void applyBackdropHighlight(Window window, Node targetNode) {
+        Scene scene = window.getScene();
+        if (scene == null || !(scene.getRoot() instanceof Pane pane)) {
+            return;
+        }
+
+        BackdropHighlight backdrop = new BackdropHighlight(pane);
+        backdrop.attach(targetNode);
+        backdropHighlights.put(window, backdrop);
+    }
+
+    private void applyPulseAnimation(Window window, Node targetNode) {
+        Scene scene = window.getScene();
+        if (scene == null || !(scene.getRoot() instanceof Pane pane)) {
+            return;
+        }
+
+        PulseAnimateIndicator pulse = new PulseAnimateIndicator(pane);
+        pulse.attach(targetNode);
+        pulseIndicators.put(window, pulse);
+    }
+
+    private void applyFullScreenDarken(Window window) {
+        Scene scene = window.getScene();
+        if (scene == null || !(scene.getRoot() instanceof Pane pane)) {
+            return;
+        }
+
+        FullScreenDarken fullDarken = new FullScreenDarken(pane);
+        fullDarken.attach();
+        fullScreenDarkens.put(window, fullDarken);
+    }
+}

jabgui/src/main/java/org/jabref/gui/walkthrough/MultiWindowWalkthroughOverlay.java

@@ -0,0 +1,128 @@
+package org.jabref.gui.walkthrough;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+
+import javafx.animation.KeyFrame;
+import javafx.animation.Timeline;
+import javafx.scene.Node;
+import javafx.scene.Scene;
+import javafx.stage.Stage;
+import javafx.stage.Window;
+import javafx.util.Duration;
+
+import org.jabref.gui.walkthrough.declarative.WindowResolver;
+import org.jabref.gui.walkthrough.declarative.step.WalkthroughNode;
+
+import org.jspecify.annotations.NonNull;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * Manages walkthrough overlays and highlights across multiple windows.
+ */
+public class MultiWindowWalkthroughOverlay {
+    private static final Logger LOGGER = LoggerFactory.getLogger(MultiWindowWalkthroughOverlay.class);
+
+    private final Map<Window, SingleWindowOverlay> overlays = new HashMap<>();
+    private final Stage mainStage;
+    private final HighlightManager highlightManager;
+    private final Walkthrough walkthrough;
+    private Timeline nodePollingTimeline;
+
+    public MultiWindowWalkthroughOverlay(Stage mainStage, Walkthrough walkthrough) {
+        this.mainStage = mainStage;
+        this.walkthrough = walkthrough;
+        this.highlightManager = new HighlightManager();
+    }
+
+    public void displayStep(@NonNull WalkthroughNode step) {
+        overlays.values().forEach(SingleWindowOverlay::hide);
+        Window activeWindow = step.activeWindowResolver().flatMap(WindowResolver::resolve).orElse(mainStage);
+        Scene scene = activeWindow.getScene();
+
+        Optional<Node> targetNode = step.resolver().resolve(scene);
+        if (targetNode.isEmpty()) {
+            if (step.autoFallback()) {
+                tryRevertToPreviousResolvableStep();
+            } else {
+                startNodePolling(step, activeWindow);
+            }
+            return;
+        }
+
+        if (step.highlight().isPresent()) {
+            highlightManager.applyHighlight(scene, step.highlight(), targetNode);
+        }
+
+        SingleWindowOverlay overlay = getOrCreateOverlay(activeWindow);
+        overlay.displayStep(step, targetNode.get(), walkthrough);
+    }
+
+    public void detachAll() {
+        stopNodePolling();
+        highlightManager.detachAll();
+        overlays.values().forEach(SingleWindowOverlay::detach);
+        overlays.clear();
+    }
+
+    private void tryRevertToPreviousResolvableStep() {
+        LOGGER.info("Attempting to revert to previous resolvable step");
+
+        int currentIndex = walkthrough.currentStepProperty().get();
+        for (int i = currentIndex - 1; i >= 0; i--) {
+            WalkthroughNode previousStep = getStepAtIndex(i);
+            Window activeWindow = previousStep.activeWindowResolver().flatMap(WindowResolver::resolve).orElse(mainStage);
+            Scene scene = activeWindow.getScene();
+            if (scene != null && previousStep.resolver().resolve(scene).isPresent()) {
+                LOGGER.info("Reverting to step {} from step {}", i, currentIndex);
+                walkthrough.goToStep(i);
+                return;
+            }
+        }
+
+        LOGGER.warn("No previous resolvable step found, staying at current step");
+    }
+
+    private void startNodePolling(WalkthroughNode step, Window activeWindow) {
+        LOGGER.info("Auto-fallback disabled for step: {}, starting node polling", step.title());
+        stopNodePolling();
+
+        nodePollingTimeline = new Timeline(new KeyFrame(Duration.millis(100), _ -> {
+            Scene scene = activeWindow.getScene();
+            if (scene != null) {
+                Optional<Node> targetNode = step.resolver().resolve(scene);
+                if (targetNode.isPresent()) {
+                    LOGGER.info("Target node found for step: {}, displaying step", step.title());
+                    stopNodePolling();
+
+                    if (step.highlight().isPresent()) {
+                        highlightManager.applyHighlight(scene, step.highlight(), targetNode);
+                    }
+
+                    SingleWindowOverlay overlay = getOrCreateOverlay(activeWindow);
+                    overlay.displayStep(step, targetNode.get(), walkthrough);
+                }
+            }
+        }));
+
+        nodePollingTimeline.setCycleCount(Timeline.INDEFINITE);
+        nodePollingTimeline.play();
+    }
+
+    private void stopNodePolling() {
+        if (nodePollingTimeline != null) {
+            nodePollingTimeline.stop();
+            nodePollingTimeline = null;
+        }
+    }
+
+    private @NonNull WalkthroughNode getStepAtIndex(int index) {
+        return walkthrough.getSteps().get(index);
+    }
+
+    private SingleWindowOverlay getOrCreateOverlay(Window window) {
+        return overlays.computeIfAbsent(window, SingleWindowOverlay::new);
+    }
+}