feat(onboarding): guided management and board tours

.dockerignore

@@ -9,4 +9,7 @@ README.md
 .git
 dev
 .build
-e2e
+e2e
+.env
+.env.*
+!.env.example

apps/nextjs/package.json

@@ -19,6 +19,7 @@
     "@dnd-kit/modifiers": "catalog:",
     "@dnd-kit/sortable": "catalog:",
     "@dnd-kit/utilities": "catalog:",
+    "@gfazioli/mantine-onboarding-tour": "catalog:",
     "@homarr/analytics": "workspace:^0.1.0",
     "@homarr/api": "workspace:^0.1.0",
     "@homarr/auth": "workspace:^0.1.0",

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

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> }) => {

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`}>
-        <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,37 +176,43 @@ const EditModeMenu = () => {
   usePreventLeaveWithDirty(isEditMode);
 
   return (
-    <HeaderButton onClick={toggle} loading={isPending}>
-      {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>
   );
 };
 
 const SelectBoardsMenu = () => {
   const { data: boards = [] } = clientApi.board.getAllBoards.useQuery();
 
   return (
-    <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>
+    <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>
   );
 };
 

apps/nextjs/src/app/[locale]/boards/_layout-creator.tsx

@@ -11,6 +11,7 @@ import { createLogger } from "@homarr/core/infrastructure/logs";
 import { MainHeader } from "~/components/layout/header";
 import { BoardLogoWithTitle } from "~/components/layout/logo/board-logo";
 import { ClientShell } from "~/components/layout/shell";
+import { BoardTourProvider } from "~/components/onboarding/board-tour";
 import { getCurrentColorSchemeAsync } from "~/theme/color-scheme";
 import type { Board } from "./_types";
 import type { Params } from "./(content)/_creator";
@@ -20,14 +21,21 @@ import { BoardMantineProvider } from "./(content)/_theme";
 
 const logger = createLogger({ module: "createBoardLayout" });
 
+const BoardTourWrapper = ({ hasSession, children }: PropsWithChildren<{ hasSession: boolean }>) => {
+  if (!hasSession) return <>{children}</>;
+  return <BoardTourProvider>{children}</BoardTourProvider>;
+};
+
 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,
@@ -61,14 +69,16 @@ export const createBoardLayout = <TParams extends Params>({
           <EditModeProvider>
             <BoardMantineProvider defaultColorScheme={colorScheme}>
               <CustomCss />
-              <ClientShell hasNavigation={false}>
-                <MainHeader
-                  logo={<BoardLogoWithTitle size="md" hideTitleOnMobile />}
-                  actions={headerActions}
-                  hasNavigation={false}
-                />
-                <AppShellMain>{children}</AppShellMain>
-              </ClientShell>
+              <BoardTourWrapper hasSession={withTour && !!session}>
+                <ClientShell hasNavigation={false}>
+                  <MainHeader
+                    logo={<BoardLogoWithTitle size="md" hideTitleOnMobile />}
+                    actions={headerActions}
+                    hasNavigation={false}
+                  />
+                  <AppShellMain>{children}</AppShellMain>
+                </ClientShell>
+              </BoardTourWrapper>
             </BoardMantineProvider>
           </EditModeProvider>
         </BoardReadyProvider>

apps/nextjs/src/app/[locale]/layout.tsx

@@ -1,6 +1,7 @@
 import type { Metadata, Viewport } from "next";
 import { Inter } from "next/font/google";
 
+import "@gfazioli/mantine-onboarding-tour/styles.css";
 import "@homarr/notifications/styles.css";
 import "@homarr/spotlight/styles.css";
 import "@homarr/ui/styles.css";

apps/nextjs/src/app/[locale]/manage/apps/page.tsx

@@ -11,6 +11,7 @@ import type { inferSearchParamsFromSchema } from "@homarr/common/types";
 import { getI18n, getScopedI18n } from "@homarr/translation/server";
 import { Link, SearchInput, TablePagination } from "@homarr/ui";
 
+import { TourTarget } from "~/components/layout/header/tour-target";
 import { ManageContainer } from "~/components/manage/manage-container";
 import { MobileAffixButton } from "~/components/manage/mobile-affix-button";
 import { DynamicBreadcrumb } from "~/components/navigation/dynamic-breadcrumb";
@@ -47,19 +48,21 @@ export default async function AppsPage(props: AppsPageProps) {
         <Group justify="space-between" align="center">
           <SearchInput placeholder={`${t("search")}...`} defaultValue={searchParams.search} flexExpand />
           {session.user.permissions.includes("app-create") && (
-            <MobileAffixButton component={Link} href="/manage/apps/new">
-              {t("page.create.title")}
-            </MobileAffixButton>
+            <TourTarget id="manage-apps-create">
+              <MobileAffixButton component={Link} href="/manage/apps/new">
+                {t("page.create.title")}
+              </MobileAffixButton>
+            </TourTarget>
           )}
         </Group>
-        {apps.length === 0 && <AppNoResults />}
-        {apps.length > 0 && (
+        <TourTarget id="manage-apps-list">
           <Stack gap="sm">
+            {apps.length === 0 && <AppNoResults />}
             {apps.map((app) => (
               <AppCard key={app.id} app={app} />
             ))}
           </Stack>
-        )}
+        </TourTarget>
 
         {/* Added margin to not hide pagination behind affix-button */}
         <Group justify="end" mb={48}>

apps/nextjs/src/app/[locale]/manage/boards/page.tsx

@@ -23,6 +23,7 @@ import { getScopedI18n } from "@homarr/translation/server";
 import { Link, UserAvatar } from "@homarr/ui";
 
 import { getBoardPermissionsAsync } from "~/components/board/permissions/server";
+import { TourTarget } from "~/components/layout/header/tour-target";
 import { ManageContainer } from "~/components/manage/manage-container";
 import { DynamicBreadcrumb } from "~/components/navigation/dynamic-breadcrumb";
 import { BoardCardMenuDropdown } from "./_components/board-card-menu-dropdown";
@@ -40,16 +41,22 @@ export default async function ManageBoardsPage() {
       <Stack>
         <Group justify="space-between">
           <Title mb="md">{t("title")}</Title>
-          {canCreateBoards && <CreateBoardButton />}
+          {canCreateBoards && (
+            <TourTarget id="manage-boards-create">
+              <CreateBoardButton />
+            </TourTarget>
+          )}
         </Group>
 
-        <Grid mb={{ base: "xl", md: 0 }}>
-          {boards.map((board) => (
-            <GridCol span={{ base: 12, md: 6 }} key={board.id}>
-              <BoardCard board={board} />
-            </GridCol>
-          ))}
-        </Grid>
+        <TourTarget id="manage-boards-list">
+          <Grid mb={{ base: "xl", md: 0 }}>
+            {boards.map((board) => (
+              <GridCol span={{ base: 12, md: 6 }} key={board.id}>
+                <BoardCard board={board} />
+              </GridCol>
+            ))}
+          </Grid>
+        </TourTarget>
       </Stack>
     </ManageContainer>
   );

apps/nextjs/src/app/[locale]/manage/integrations/page.tsx

@@ -37,6 +37,7 @@ import { getIntegrationName } from "@homarr/definitions";
 import { getScopedI18n } from "@homarr/translation/server";
 import { CountBadge, IntegrationAvatar, Link } from "@homarr/ui";
 
+import { TourTarget } from "~/components/layout/header/tour-target";
 import { ManageContainer } from "~/components/manage/manage-container";
 import { DynamicBreadcrumb } from "~/components/navigation/dynamic-breadcrumb";
 import { NoResults } from "~/components/no-results";
@@ -84,18 +85,22 @@ export default async function IntegrationsPage(props: IntegrationsPageProps) {
                 </IntegrationSelectMenu>
               </Box>
 
-              <Box visibleFrom="md">
-                <IntegrationSelectMenu>
-                  <MenuTarget>
-                    <Button rightSection={<IconChevronDown size={16} stroke={1.5} />}>{t("action.create")}</Button>
-                  </MenuTarget>
-                </IntegrationSelectMenu>
-              </Box>
+              <TourTarget id="manage-integrations-create">
+                <Box visibleFrom="md">
+                  <IntegrationSelectMenu>
+                    <MenuTarget>
+                      <Button rightSection={<IconChevronDown size={16} stroke={1.5} />}>{t("action.create")}</Button>
+                    </MenuTarget>
+                  </IntegrationSelectMenu>
+                </Box>
+              </TourTarget>
             </>
           )}
         </Group>
 
-        <IntegrationList integrations={integrations} activeTab={searchParams.tab} />
+        <TourTarget id="manage-integrations-list">
+          <IntegrationList integrations={integrations} activeTab={searchParams.tab} />
+        </TourTarget>
       </Stack>
     </ManageContainer>
   );