feat: restore opt-in first-run onboarding

src/serviceFeatures/setupObsidian/setupManagerHandlers.ts

@@ -1,8 +1,38 @@
 import { type SetupManager, UserMode } from "@/modules/features/SetupManager";
 import type { SetupFeatureHost } from "@/serviceFeatures/setupObsidian/types";
-import { EVENT_REQUEST_OPEN_P2P_SETTINGS, EVENT_REQUEST_OPEN_SETUP_URI } from "@vrtmrz/livesync-commonlib/compat/events/coreEvents";
+import {
+    EVENT_REQUEST_OPEN_P2P_SETTINGS,
+    EVENT_REQUEST_OPEN_SETUP_URI,
+} from "@vrtmrz/livesync-commonlib/compat/events/coreEvents";
 import { fireAndForget } from "@vrtmrz/livesync-commonlib/compat/common/utils";
 import type { NecessaryServices } from "@vrtmrz/livesync-commonlib/compat/interfaces/ServiceModule";
+import { $msg } from "@vrtmrz/livesync-commonlib/compat/common/i18n";
+
+const ONBOARDING_NOTICE_DURATION_MS = 60_000;
+
+export async function openOnboarding(setupManager: SetupManager) {
+    return await setupManager.startOnBoarding();
+}
+
+export function showOnboardingInvitation(host: NecessaryServices<"UI", never>, setupManager: SetupManager): void {
+    const message = `${$msg("Welcome to Self-hosted LiveSync")} ${$msg(
+        "We will now guide you through a few questions to simplify the synchronisation setup."
+    )} {HERE}`;
+    host.services.UI.confirm.askInPopup(
+        "initial-onboarding",
+        message,
+        (anchor) => {
+            anchor.href = "#";
+            anchor.classList.add("sls-onboarding-invitation-action");
+            anchor.textContent = $msg("Ui.SetupWizard.Invitation.Start");
+            anchor.addEventListener("click", (event) => {
+                event.preventDefault();
+                fireAndForget(() => openOnboarding(setupManager));
+            });
+        },
+        ONBOARDING_NOTICE_DURATION_MS
+    );
+}
 
 export async function openSetupURI(setupManager: SetupManager) {
     await setupManager.onUseSetupURI(UserMode.Unknown);
@@ -17,6 +47,11 @@ export function useSetupManagerHandlersFeature(
     setupManager: SetupManager
 ) {
     host.services.appLifecycle.onLoaded.addHandler(() => {
+        host.services.API.addCommand({
+            id: "livesync-open-onboarding",
+            name: "Open onboarding wizard",
+            callback: () => fireAndForget(() => openOnboarding(setupManager)),
+        });
         host.services.API.addCommand({
             id: "livesync-opensetupuri",
             name: "Use the copied setup URI (Formerly Open setup URI)",

src/serviceFeatures/setupObsidian/setupManagerHandlers.unit.spec.ts

@@ -1,6 +1,15 @@
 import { describe, expect, it, vi, afterEach } from "vitest";
-import { EVENT_REQUEST_OPEN_P2P_SETTINGS, EVENT_REQUEST_OPEN_SETUP_URI } from "@vrtmrz/livesync-commonlib/compat/events/coreEvents";
-import { openP2PSettings, openSetupURI, useSetupManagerHandlersFeature } from "./setupManagerHandlers";
+import {
+    EVENT_REQUEST_OPEN_P2P_SETTINGS,
+    EVENT_REQUEST_OPEN_SETUP_URI,
+} from "@vrtmrz/livesync-commonlib/compat/events/coreEvents";
+import {
+    openOnboarding,
+    openP2PSettings,
+    openSetupURI,
+    showOnboardingInvitation,
+    useSetupManagerHandlersFeature,
+} from "./setupManagerHandlers";
 
 vi.mock("@/modules/features/SetupManager", () => {
     return {
@@ -43,6 +52,63 @@ describe("setupObsidian/setupManagerHandlers", () => {
         expect(setupManager.onP2PManualSetup).toHaveBeenCalledWith("unknown", settings, false);
     });
 
+    it("openOnboarding should delegate to SetupManager.startOnBoarding", async () => {
+        const setupManager = {
+            startOnBoarding: vi.fn(async () => await Promise.resolve(false)),
+        } as any;
+
+        await openOnboarding(setupManager);
+
+        expect(setupManager.startOnBoarding).toHaveBeenCalledOnce();
+    });
+
+    it("showOnboardingInvitation should wait for its fixed action link before opening onboarding", async () => {
+        let configureAnchor: ((anchor: HTMLAnchorElement) => void) | undefined;
+        const askInPopup = vi.fn(
+            (_key: string, _text: string, callback: (anchor: HTMLAnchorElement) => void, _durationMs?: number) => {
+                configureAnchor = callback;
+            }
+        );
+        const host = {
+            services: {
+                UI: { confirm: { askInPopup } },
+            },
+        } as any;
+        const setupManager = {
+            startOnBoarding: vi.fn(async () => await Promise.resolve(false)),
+        } as any;
+
+        showOnboardingInvitation(host, setupManager);
+
+        expect(setupManager.startOnBoarding).not.toHaveBeenCalled();
+        expect(askInPopup).toHaveBeenCalledWith(
+            "initial-onboarding",
+            expect.stringContaining("{HERE}"),
+            expect.any(Function),
+            60_000
+        );
+
+        let click: ((event: { preventDefault(): void }) => void) | undefined;
+        const addClass = vi.fn();
+        const anchor = {
+            href: "",
+            textContent: "",
+            classList: { add: addClass },
+            addEventListener: vi.fn((_name: string, listener: typeof click) => {
+                click = listener;
+            }),
+        } as unknown as HTMLAnchorElement;
+        configureAnchor!(anchor);
+
+        expect(anchor.href).toBe("#");
+        expect(anchor.textContent).toBe("Start setup");
+        expect(addClass).toHaveBeenCalledWith("sls-onboarding-invitation-action");
+        const preventDefault = vi.fn();
+        click!({ preventDefault });
+        await vi.waitFor(() => expect(setupManager.startOnBoarding).toHaveBeenCalledOnce());
+        expect(preventDefault).toHaveBeenCalledOnce();
+    });
+
     it("useSetupManagerHandlersFeature should register onLoaded handler that wires command and events", async () => {
         const addHandler = vi.fn();
         const addCommand = vi.fn();
@@ -54,6 +120,11 @@ describe("setupObsidian/setupManagerHandlers", () => {
                 API: {
                     addCommand,
                 },
+                UI: {
+                    confirm: {
+                        askInPopup: vi.fn(),
+                    },
+                },
                 appLifecycle: {
                     onLoaded: {
                         addHandler,
@@ -65,6 +136,7 @@ describe("setupObsidian/setupManagerHandlers", () => {
             },
         } as any;
         const setupManager = {
+            startOnBoarding: vi.fn(async () => await Promise.resolve(false)),
             onUseSetupURI: vi.fn(async () => await Promise.resolve(true)),
             onP2PManualSetup: vi.fn(async () => await Promise.resolve(true)),
         } as any;
@@ -75,6 +147,12 @@ describe("setupObsidian/setupManagerHandlers", () => {
         const loadedHandler = addHandler.mock.calls[0][0] as () => Promise<boolean>;
         await loadedHandler();
 
+        expect(addCommand).toHaveBeenCalledWith(
+            expect.objectContaining({
+                id: "livesync-open-onboarding",
+                name: "Open onboarding wizard",
+            })
+        );
         expect(addCommand).toHaveBeenCalledWith(
             expect.objectContaining({
                 id: "livesync-opensetupuri",