From 60bf8672039c6b547ad7bdf6d8df329468e3fc48 Mon Sep 17 00:00:00 2001
From: Thomas Camlong <thomas@ajnart.fr>
Date: Wed, 20 May 2026 09:43:00 +0200
Subject: [PATCH] feat(onboarding): add board tour on dashboard pages

Scope the board tour to content pages, target header actions, remove the
loading overlay, and persist completion with optimistic cache updates.
---
 .../app/[locale]/boards/(content)/_client.tsx | 13 +---
 .../[locale]/boards/(content)/_creator.tsx    |  1 +
 .../boards/(content)/_header-actions.tsx      | 65 +++++++++++--------
 .../app/[locale]/boards/_layout-creator.tsx   |  4 +-
 .../src/components/onboarding/board-tour.tsx  | 59 ++++++++++-------
 5 files changed, 78 insertions(+), 64 deletions(-)

diff --git a/apps/nextjs/src/app/[locale]/boards/(content)/_client.tsx b/apps/nextjs/src/app/[locale]/boards/(content)/_client.tsx
index e9551af52..649aa867b 100644
--- a/apps/nextjs/src/app/[locale]/boards/(content)/_client.tsx
+++ b/apps/nextjs/src/app/[locale]/boards/(content)/_client.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useCallback, useRef } from "react";
-import { Box, LoadingOverlay, Stack } from "@mantine/core";
+import { Box, Stack } from "@mantine/core";
 
 import type { RouterOutputs } from "@homarr/api";
 import { clientApi } from "@homarr/api/client";
@@ -10,8 +10,6 @@ import { useCurrentLayout, useRequiredBoard } from "@homarr/boards/context";
 import { BoardCategorySection } from "~/components/board/sections/category-section";
 import { BoardEmptySection } from "~/components/board/sections/empty-section";
 import { BoardBackgroundVideo } from "~/components/layout/background";
-import { fullHeightWithoutHeaderAndFooter } from "~/constants";
-import { useIsBoardReady } from "./_ready-context";
 
 let boardName: string | null = null;
 
@@ -44,7 +42,6 @@ export const useUpdateBoard = () => {
 export const ClientBoard = () => {
   const board = useRequiredBoard();
   const currentLayoutId = useCurrentLayout();
-  const isReady = useIsBoardReady();
 
   const fullWidthSortedSections = board.sections
     .filter((section) => section.kind === "empty" || section.kind === "category")
@@ -55,13 +52,7 @@ export const ClientBoard = () => {
   return (
     <Box h="100%" pos="relative">
       <BoardBackgroundVideo />
-      <LoadingOverlay
-        visible={!isReady}
-        transitionProps={{ duration: 500 }}
-        loaderProps={{ size: "lg" }}
-        h={fullHeightWithoutHeaderAndFooter}
-      />
-      <Stack ref={ref} h="100%" style={{ visibility: isReady ? "visible" : "hidden" }}>
+      <Stack ref={ref} h="100%">
         {fullWidthSortedSections.map((section) =>
           section.kind === "empty" ? (
             // Unique keys per layout to always reinitialize the gridstack
diff --git a/apps/nextjs/src/app/[locale]/boards/(content)/_creator.tsx b/apps/nextjs/src/app/[locale]/boards/(content)/_creator.tsx
index 64c9289e3..0ad398608 100644
--- a/apps/nextjs/src/app/[locale]/boards/(content)/_creator.tsx
+++ b/apps/nextjs/src/app/[locale]/boards/(content)/_creator.tsx
@@ -38,6 +38,7 @@ export const createBoardContentPage = <TParams extends Record<string, unknown>>(
     layout: createBoardLayout({
       headerActions: <BoardContentHeaderActions />,
       getInitialBoardAsync: getInitialBoard,
+      withTour: true,
     }),
     // eslint-disable-next-line no-restricted-syntax
     page: async ({ params }: { params: Promise<TParams> }) => {
diff --git a/apps/nextjs/src/app/[locale]/boards/(content)/_header-actions.tsx b/apps/nextjs/src/app/[locale]/boards/(content)/_header-actions.tsx
index 18c0fe241..c76d29ea0 100644
--- a/apps/nextjs/src/app/[locale]/boards/(content)/_header-actions.tsx
+++ b/apps/nextjs/src/app/[locale]/boards/(content)/_header-actions.tsx
@@ -2,7 +2,8 @@
 
 import { useCallback, useEffect } from "react";
 import { useRouter } from "next/navigation";
-import { Group, Menu, ScrollArea } from "@mantine/core";
+import { OnboardingTour } from "@gfazioli/mantine-onboarding-tour";
+import { Box, Group, Menu, ScrollArea } from "@mantine/core";
 import { useHotkeys } from "@mantine/hooks";
 import {
   IconBox,
@@ -53,9 +54,11 @@ export const BoardContentHeaderActions = () => {
 
       <EditModeMenu />
 
-      <HeaderButton href={`/boards/${board.name}/settings`} data-onboarding-tour-id="board-settings">
-        <IconSettings stroke={1.5} />
-      </HeaderButton>
+      <OnboardingTour.Target id="board-settings">
+        <HeaderButton href={`/boards/${board.name}/settings`}>
+          <IconSettings stroke={1.5} />
+        </HeaderButton>
+      </OnboardingTour.Target>
 
       <SelectBoardsMenu />
     </>
@@ -173,9 +176,11 @@ const EditModeMenu = () => {
   usePreventLeaveWithDirty(isEditMode);
 
   return (
-    <HeaderButton onClick={toggle} loading={isPending} data-onboarding-tour-id="board-edit-mode">
-      {isEditMode ? <IconPencilOff stroke={1.5} /> : <IconPencil stroke={1.5} />}
-    </HeaderButton>
+    <OnboardingTour.Target id="board-edit-mode">
+      <HeaderButton onClick={toggle} loading={isPending}>
+        {isEditMode ? <IconPencilOff stroke={1.5} /> : <IconPencil stroke={1.5} />}
+      </HeaderButton>
+    </OnboardingTour.Target>
   );
 };
 
@@ -183,27 +188,31 @@ const SelectBoardsMenu = () => {
   const { data: boards = [] } = clientApi.board.getAllBoards.useQuery();
 
   return (
-    <Menu position="bottom-end" withArrow>
-      <Menu.Target>
-        <HeaderButton w="auto" px={4} data-onboarding-tour-id="board-switcher">
-          <IconReplace stroke={1.5} />
-        </HeaderButton>
-      </Menu.Target>
-      <Menu.Dropdown style={{ transform: "translate(-7px, 0)" }}>
-        <ScrollArea.Autosize mah={300}>
-          {boards.map((board) => (
-            <Menu.Item
-              key={board.id}
-              component={Link}
-              href={`/boards/${board.name}`}
-              leftSection={<IconLayoutBoard size={20} />}
-            >
-              {board.name}
-            </Menu.Item>
-          ))}
-        </ScrollArea.Autosize>
-      </Menu.Dropdown>
-    </Menu>
+    <OnboardingTour.Target id="board-switcher">
+      <Box>
+        <Menu position="bottom-end" withArrow>
+          <Menu.Target>
+            <HeaderButton w="auto" px={4}>
+              <IconReplace stroke={1.5} />
+            </HeaderButton>
+          </Menu.Target>
+          <Menu.Dropdown style={{ transform: "translate(-7px, 0)" }}>
+            <ScrollArea.Autosize mah={300}>
+              {boards.map((board) => (
+                <Menu.Item
+                  key={board.id}
+                  component={Link}
+                  href={`/boards/${board.name}`}
+                  leftSection={<IconLayoutBoard size={20} />}
+                >
+                  {board.name}
+                </Menu.Item>
+              ))}
+            </ScrollArea.Autosize>
+          </Menu.Dropdown>
+        </Menu>
+      </Box>
+    </OnboardingTour.Target>
   );
 };
 
diff --git a/apps/nextjs/src/app/[locale]/boards/_layout-creator.tsx b/apps/nextjs/src/app/[locale]/boards/_layout-creator.tsx
index 972577ed7..3cddc6685 100644
--- a/apps/nextjs/src/app/[locale]/boards/_layout-creator.tsx
+++ b/apps/nextjs/src/app/[locale]/boards/_layout-creator.tsx
@@ -29,11 +29,13 @@ const BoardTourWrapper = ({ hasSession, children }: PropsWithChildren<{ hasSessi
 interface CreateBoardLayoutProps<TParams extends Params> {
   headerActions: JSX.Element;
   getInitialBoardAsync: (params: TParams) => Promise<Board>;
+  withTour?: boolean;
 }
 
 export const createBoardLayout = <TParams extends Params>({
   headerActions,
   getInitialBoardAsync: getInitialBoard,
+  withTour = false,
 }: CreateBoardLayoutProps<TParams>) => {
   const Layout = async ({
     params,
@@ -67,7 +69,7 @@ export const createBoardLayout = <TParams extends Params>({
           <EditModeProvider>
             <BoardMantineProvider defaultColorScheme={colorScheme}>
               <CustomCss />
-              <BoardTourWrapper hasSession={!!session}>
+              <BoardTourWrapper hasSession={withTour && !!session}>
                 <ClientShell hasNavigation={false}>
                   <MainHeader
                     logo={<BoardLogoWithTitle size="md" hideTitleOnMobile />}
diff --git a/apps/nextjs/src/components/onboarding/board-tour.tsx b/apps/nextjs/src/components/onboarding/board-tour.tsx
index b7a9d76da..d7f5d2765 100644
--- a/apps/nextjs/src/components/onboarding/board-tour.tsx
+++ b/apps/nextjs/src/components/onboarding/board-tour.tsx
@@ -3,26 +3,35 @@
 import type { PropsWithChildren } from "react";
 import { useMemo } from "react";
 import type { OnboardingTourStep } from "@gfazioli/mantine-onboarding-tour";
-import { OnboardingTour } from "@gfazioli/mantine-onboarding-tour";
 
 import { clientApi } from "@homarr/api/client";
 import { useRequiredBoard } from "@homarr/boards/context";
+import { createDocumentationLink } from "@homarr/definitions";
 import { useScopedI18n } from "@homarr/translation/client";
 
 import { useBoardPermissions } from "~/components/board/permissions/client";
-import { SkipHoldButton } from "./skip-hold-button";
+import { TourShell } from "./tour-shell";
 import { TourStepContent } from "./tour-step-content";
 
 export const BoardTourProvider = ({ children }: PropsWithChildren) => {
   const t = useScopedI18n("onboardingTour.board");
   const board = useRequiredBoard();
   const { hasChangeAccess } = useBoardPermissions(board);
+  const utils = clientApi.useUtils();
   const { data: tourStatus } = clientApi.user.getTourStatus.useQuery();
-  const { mutate: completeTour } = clientApi.user.completeTour.useMutation();
+  const { mutate: completeTour } = clientApi.user.completeTour.useMutation({
+    onSuccess() {
+      void utils.user.getTourStatus.invalidate();
+    },
+  });
 
   const started = tourStatus !== undefined && !tourStatus.completedBoardTour;
 
   const handleEnd = () => {
+    utils.user.getTourStatus.setData(undefined, {
+      completedManageTour: tourStatus?.completedManageTour ?? false,
+      completedBoardTour: true,
+    });
     completeTour({ tour: "board" });
   };
 
@@ -34,13 +43,12 @@ export const BoardTourProvider = ({ children }: PropsWithChildren) => {
         content: (
           <TourStepContent
             description={t("welcome.description")}
-            docPath="/docs/getting-started/after-the-installation"
-            docHash="#creating-your-first-board"
+            documentationHref={createDocumentationLink(
+              "/docs/getting-started/after-the-installation",
+              "#creating-your-first-board",
+            )}
           />
         ),
-        footer: (controller: { skipTour: () => void }) => (
-          <SkipHoldButton onSkip={() => controller.skipTour()} />
-        ),
       },
       {
         id: "board-edit-mode",
@@ -49,8 +57,10 @@ export const BoardTourProvider = ({ children }: PropsWithChildren) => {
         content: (
           <TourStepContent
             description={t("editMode.description")}
-            docPath="/docs/getting-started/after-the-installation"
-            docHash="#arrange-and-organize-your-board"
+            documentationHref={createDocumentationLink(
+              "/docs/getting-started/after-the-installation",
+              "#arrange-and-organize-your-board",
+            )}
           />
         ),
       },
@@ -59,39 +69,40 @@ export const BoardTourProvider = ({ children }: PropsWithChildren) => {
         title: t("settings.title"),
         requiresChangeAccess: true,
         content: (
-          <TourStepContent description={t("settings.description")} docPath="/docs/management/boards" />
+          <TourStepContent
+            description={t("settings.description")}
+            documentationHref={createDocumentationLink("/docs/management/boards")}
+          />
         ),
       },
       {
         id: "board-switcher",
         title: t("switcher.title"),
         content: (
-          <TourStepContent description={t("switcher.description")} docPath="/docs/management/boards" />
+          <TourStepContent
+            description={t("switcher.description")}
+            documentationHref={createDocumentationLink("/docs/management/boards")}
+          />
         ),
       },
       {
         id: "board-user-menu",
         title: t("userMenu.title"),
         content: (
-          <TourStepContent description={t("userMenu.description")} docPath="/docs/management/users" />
+          <TourStepContent
+            description={t("userMenu.description")}
+            documentationHref={createDocumentationLink("/docs/management/users")}
+          />
         ),
       },
     ];
 
-    return allSteps.filter(
-      (step) => !step.requiresChangeAccess || hasChangeAccess,
-    ) as OnboardingTourStep[];
+    return allSteps.filter((step) => !step.requiresChangeAccess || hasChangeAccess) as OnboardingTourStep[];
   }, [hasChangeAccess, t]);
 
   return (
-    <OnboardingTour
-      tour={steps}
-      started={started}
-      onOnboardingTourComplete={handleEnd}
-      onOnboardingTourSkip={handleEnd}
-      maw={420}
-    >
+    <TourShell steps={steps} started={started} onEnd={handleEnd} position={{ base: "bottom", sm: "left" }}>
       {children}
-    </OnboardingTour>
+    </TourShell>
   );
 };