Merge origin/feat/app-tour into insiders/ui-ux

apps/nextjs/src/components/layout/header.tsx

@@ -6,6 +6,7 @@ import { Link } from "@homarr/ui";
 
 import { ClientBurger } from "./header/burger";
 import { DesktopSearchInput, MobileSearchButton } from "./header/search";
+import { TourTarget } from "./header/tour-target";
 import { UserButton } from "./header/user";
 import { HomarrLogoWithTitle } from "./logo/homarr-logo";
 
@@ -25,11 +26,15 @@ export const MainHeader = ({ logo, actions, hasNavigation = true }: Props) => {
             {logo ?? <HomarrLogoWithTitle size="md" />}
           </UnstyledButton>
         </Group>
-        <DesktopSearchInput />
+        <TourTarget id="board-search">
+          <DesktopSearchInput />
+        </TourTarget>
         <Group h="100%" align="center" justify="end" style={{ flex: 1 }} wrap="nowrap">
           {actions}
           <MobileSearchButton />
-          <UserButton />
+          <TourTarget id="board-user-menu">
+            <UserButton />
+          </TourTarget>
         </Group>
       </Group>
       <Spotlight />

apps/nextjs/src/components/layout/header/tour-target.tsx

@@ -0,0 +1,11 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { OnboardingTour } from "@gfazioli/mantine-onboarding-tour";
+import { Box } from "@mantine/core";
+
+export const TourTarget = ({ id, children }: { id: string; children: ReactNode }) => (
+  <OnboardingTour.Target id={id}>
+    <Box data-tour-target={id}>{children}</Box>
+  </OnboardingTour.Target>
+);

apps/nextjs/src/components/layout/navigation-link.tsx

@@ -2,6 +2,7 @@
 
 import type { ReactNode } from "react";
 import { usePathname } from "next/navigation";
+import { OnboardingTour } from "@gfazioli/mantine-onboarding-tour";
 import { NavLink } from "@mantine/core";
 
 import { Link } from "@homarr/ui";
@@ -9,9 +10,15 @@ import { Link } from "@homarr/ui";
 export const CommonNavLink = (props: ClientNavigationLink) =>
   "href" in props ? <NavLinkHref {...props} /> : <NavLinkWithItems {...props} />;
 
+const TourTarget = ({ id, children }: { id?: string; children: ReactNode }) => {
+  if (!id) return <>{children}</>;
+  return <OnboardingTour.Target id={id}>{children}</OnboardingTour.Target>;
+};
+
 const NavLinkHref = (props: NavigationLinkHref) => {
   const pathname = usePathname();
-  return props.external ? (
+  const tourId = props["data-onboarding-tour-id"];
+  const link = props.external ? (
     <NavLink component="a" label={props.label} leftSection={props.icon} href={props.href} target="_blank" />
   ) : (
     <NavLink
@@ -22,23 +29,26 @@ const NavLinkHref = (props: NavigationLinkHref) => {
       active={pathname === props.href}
     />
   );
+  return <TourTarget id={tourId}>{link}</TourTarget>;
 };
 
 const NavLinkWithItems = (props: NavigationLinkWithItems) => {
   const pathname = usePathname();
   const isActive = props.items.some((item) => item.href === pathname);
-  return (
+  const nav = (
     <NavLink label={props.label} leftSection={props.icon} defaultOpened={isActive}>
       {props.items.map((item) => (
         <NavLinkHref key={item.label} {...item} />
       ))}
     </NavLink>
   );
+  return <TourTarget id={props["data-onboarding-tour-id"]}>{nav}</TourTarget>;
 };
 
 interface CommonNavigationLinkProps {
   label: string;
   icon: ReactNode;
+  "data-onboarding-tour-id"?: string;
 }
 
 interface NavigationLinkHref extends CommonNavigationLinkProps {

apps/nextjs/src/components/layout/navigation.tsx

@@ -27,7 +27,7 @@ export const MainNavigation = ({ headerSection, footerSection, links }: MainNavi
             return null;
           }
 
-          const { icon: TablerIcon, iconProps, ...props } = link;
+          const { icon: TablerIcon, iconProps, "data-onboarding-tour-id": tourId, ...props } = link;
           const Icon =
             typeof TablerIcon === "string" ? (
               <Image src={TablerIcon} w={20} h={20} />
@@ -38,17 +38,20 @@ export const MainNavigation = ({ headerSection, footerSection, links }: MainNavi
           if ("items" in props) {
             clientLink = {
               ...props,
+              "data-onboarding-tour-id": tourId,
               items: props.items
                 .filter((item) => !item.hidden)
                 .map((item) => {
+                  const { "data-onboarding-tour-id": itemTourId, ...rest } = item;
                   return {
-                    ...item,
+                    ...rest,
+                    "data-onboarding-tour-id": itemTourId,
                     icon: <item.icon size={20} stroke={1.5} {...iconProps} />,
                   };
                 }),
             } as ClientNavigationLink;
           } else {
-            clientLink = props as ClientNavigationLink;
+            clientLink = { ...props, "data-onboarding-tour-id": tourId } as ClientNavigationLink;
           }
           return <CommonNavLink key={index} {...clientLink} icon={Icon} />;
         })}
@@ -63,6 +66,7 @@ interface CommonNavigationLinkProps {
   icon: TablerIcon | string;
   iconProps?: TablerIconProps;
   hidden?: boolean;
+  "data-onboarding-tour-id"?: string;
 }
 
 interface NavigationLinkHref extends CommonNavigationLinkProps {

apps/nextjs/src/components/onboarding/board-tour.tsx

@@ -0,0 +1,108 @@
+"use client";
+
+import type { PropsWithChildren } from "react";
+import { useMemo } from "react";
+import type { OnboardingTourStep } 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 { 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({
+    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" });
+  };
+
+  const steps = useMemo(() => {
+    const allSteps: (OnboardingTourStep & { requiresChangeAccess?: boolean })[] = [
+      {
+        id: "board-search",
+        title: t("welcome.title"),
+        content: (
+          <TourStepContent
+            description={t("welcome.description")}
+            documentationHref={createDocumentationLink(
+              "/docs/getting-started/after-the-installation",
+              "#creating-your-first-board",
+            )}
+          />
+        ),
+      },
+      {
+        id: "board-edit-mode",
+        title: t("editMode.title"),
+        requiresChangeAccess: true,
+        content: (
+          <TourStepContent
+            description={t("editMode.description")}
+            documentationHref={createDocumentationLink(
+              "/docs/getting-started/after-the-installation",
+              "#arrange-and-organize-your-board",
+            )}
+          />
+        ),
+      },
+      {
+        id: "board-settings",
+        title: t("settings.title"),
+        requiresChangeAccess: true,
+        content: (
+          <TourStepContent
+            description={t("settings.description")}
+            documentationHref={createDocumentationLink("/docs/management/boards")}
+          />
+        ),
+      },
+      {
+        id: "board-switcher",
+        title: t("switcher.title"),
+        content: (
+          <TourStepContent
+            description={t("switcher.description")}
+            documentationHref={createDocumentationLink("/docs/management/boards")}
+          />
+        ),
+      },
+      {
+        id: "board-user-menu",
+        title: t("userMenu.title"),
+        content: (
+          <TourStepContent
+            description={t("userMenu.description")}
+            documentationHref={createDocumentationLink("/docs/management/users")}
+          />
+        ),
+      },
+    ];
+
+    return allSteps.filter((step) => !step.requiresChangeAccess || hasChangeAccess) as OnboardingTourStep[];
+  }, [hasChangeAccess, t]);
+
+  return (
+    <TourShell steps={steps} started={started} onEnd={handleEnd} position={{ base: "bottom", sm: "left" }}>
+      {children}
+    </TourShell>
+  );
+};

apps/nextjs/src/components/onboarding/manage-tour.tsx

@@ -0,0 +1,220 @@
+"use client";
+
+import type { PropsWithChildren } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { usePathname, useRouter } from "next/navigation";
+import type { OnboardingTourFocusRevealProps, OnboardingTourStep } from "@gfazioli/mantine-onboarding-tour";
+import { useMediaQuery } from "@mantine/hooks";
+import {
+  IconAffiliateFilled,
+  IconAppsFilled,
+  IconLayoutDashboardFilled,
+  IconPlus,
+  IconUserFilled,
+} from "@tabler/icons-react";
+
+import { clientApi } from "@homarr/api/client";
+import { createDocumentationLink } from "@homarr/definitions";
+import { useScopedI18n } from "@homarr/translation/client";
+
+import { TourShell } from "./tour-shell";
+import { TourStepContent } from "./tour-step-content";
+
+interface ManageTourProviderProps extends PropsWithChildren {
+  isAdmin: boolean;
+}
+
+const stepRoutes: Record<string, string> = {
+  "manage-welcome": "/manage",
+  "manage-boards-list": "/manage/boards",
+  "manage-boards-create": "/manage/boards",
+  "manage-apps-list": "/manage/apps",
+  "manage-apps-create": "/manage/apps",
+  "manage-integrations-list": "/manage/integrations",
+  "manage-integrations-create": "/manage/integrations",
+  "manage-users-list": "/manage/users",
+  "manage-users-create": "/manage/users",
+};
+
+const usersStepFocusRevealProps: OnboardingTourFocusRevealProps = {
+  withReveal: false,
+  popoverProps: {
+    position: "bottom",
+    middlewares: { shift: { padding: 16 }, flip: true },
+  },
+};
+
+export const ManageTourProvider = ({ children, isAdmin }: ManageTourProviderProps) => {
+  const t = useScopedI18n("onboardingTour.manage");
+  const utils = clientApi.useUtils();
+  const { data: tourStatus } = clientApi.user.getTourStatus.useQuery();
+  const { mutate: completeTour } = clientApi.user.completeTour.useMutation({
+    onSuccess() {
+      void utils.user.getTourStatus.invalidate();
+    },
+  });
+  const isMobile = useMediaQuery("(max-width: 48em)");
+  const pathname = usePathname();
+  const router = useRouter();
+
+  const isManageHome = /^(\/[^/]+)?\/manage\/?$/.test(pathname);
+  const isManageSection = /^(\/[^/]+)?\/manage(\/.*)?$/.test(pathname);
+
+  const [tourActive, setTourActive] = useState(false);
+  const [tourDismissed, setTourDismissed] = useState(false);
+  const wasManageTourCompletedRef = useRef(tourStatus?.completedManageTour);
+
+  useEffect(() => {
+    if (tourDismissed) return;
+    if (isManageHome && tourStatus !== undefined && !tourStatus.completedManageTour && !isMobile) {
+      setTourActive(true);
+    }
+  }, [isManageHome, tourStatus, isMobile, tourDismissed]);
+
+  useEffect(() => {
+    if (!isManageSection) {
+      setTourActive(false);
+    }
+  }, [isManageSection]);
+
+  useEffect(() => {
+    const wasCompleted = wasManageTourCompletedRef.current;
+    const isCompleted = tourStatus?.completedManageTour;
+    if (wasCompleted === true && isCompleted === false) {
+      setTourDismissed(false);
+    }
+    wasManageTourCompletedRef.current = isCompleted;
+  }, [tourStatus?.completedManageTour]);
+
+  const handleEnd = useCallback(() => {
+    setTourDismissed(true);
+    setTourActive(false);
+    utils.user.getTourStatus.setData(undefined, {
+      completedManageTour: true,
+      completedBoardTour: tourStatus?.completedBoardTour ?? false,
+    });
+    completeTour({ tour: "manage" });
+    router.push("/manage");
+  }, [completeTour, router, tourStatus?.completedBoardTour, utils.user.getTourStatus]);
+
+  const steps = useMemo(() => {
+    const allSteps: (OnboardingTourStep & { adminOnly?: boolean })[] = [
+      {
+        id: "manage-welcome",
+        title: t("welcome.title"),
+        content: (
+          <TourStepContent
+            description={t("welcome.description")}
+            documentationHref={createDocumentationLink("/docs/category/management")}
+          />
+        ),
+      },
+      {
+        id: "manage-boards-list",
+        title: t("boardsList.title"),
+        content: (
+          <TourStepContent
+            description={t("boardsList.description")}
+            documentationHref={createDocumentationLink("/docs/management/boards")}
+            icon={<IconLayoutDashboardFilled size={18} />}
+          />
+        ),
+      },
+      {
+        id: "manage-boards-create",
+        title: t("boardsCreate.title"),
+        content: (
+          <TourStepContent
+            description={t("boardsCreate.description")}
+            documentationHref={createDocumentationLink("/docs/management/boards")}
+            icon={<IconPlus size={18} />}
+          />
+        ),
+      },
+      {
+        id: "manage-apps-list",
+        title: t("appsList.title"),
+        content: (
+          <TourStepContent
+            description={t("appsList.description")}
+            documentationHref={createDocumentationLink("/docs/management/apps")}
+            icon={<IconAppsFilled size={18} />}
+          />
+        ),
+      },
+      {
+        id: "manage-apps-create",
+        title: t("appsCreate.title"),
+        content: (
+          <TourStepContent
+            description={t("appsCreate.description")}
+            documentationHref={createDocumentationLink("/docs/management/apps")}
+            icon={<IconPlus size={18} />}
+          />
+        ),
+      },
+      {
+        id: "manage-integrations-list",
+        title: t("integrationsList.title"),
+        content: (
+          <TourStepContent
+            description={t("integrationsList.description")}
+            documentationHref={createDocumentationLink("/docs/management/integrations")}
+            icon={<IconAffiliateFilled size={18} />}
+          />
+        ),
+      },
+      {
+        id: "manage-integrations-create",
+        title: t("integrationsCreate.title"),
+        content: (
+          <TourStepContent
+            description={t("integrationsCreate.description")}
+            documentationHref={createDocumentationLink("/docs/management/integrations")}
+            icon={<IconPlus size={18} />}
+          />
+        ),
+      },
+      {
+        id: "manage-users-list",
+        title: t("usersList.title"),
+        adminOnly: true,
+        focusRevealProps: usersStepFocusRevealProps,
+        content: (
+          <TourStepContent
+            description={t("usersList.description")}
+            documentationHref={createDocumentationLink("/docs/management/users")}
+            icon={<IconUserFilled size={18} />}
+          />
+        ),
+      },
+      {
+        id: "manage-users-create",
+        title: t("usersCreate.title"),
+        adminOnly: true,
+        focusRevealProps: usersStepFocusRevealProps,
+        content: (
+          <TourStepContent
+            description={t("usersCreate.description")}
+            documentationHref={createDocumentationLink("/docs/management/users")}
+            icon={<IconPlus size={18} />}
+          />
+        ),
+      },
+    ];
+
+    return allSteps.filter((step) => !step.adminOnly || isAdmin) as OnboardingTourStep[];
+  }, [isAdmin, t]);
+
+  return (
+    <TourShell
+      steps={steps}
+      started={tourActive}
+      onEnd={handleEnd}
+      stepRoutes={stepRoutes}
+      position={{ base: "bottom", sm: "right" }}
+    >
+      {children}
+    </TourShell>
+  );
+};

apps/nextjs/src/components/onboarding/tour-shell.tsx

@@ -0,0 +1,197 @@
+"use client";
+
+import type { PropsWithChildren } from "react";
+import { useCallback, useEffect, useRef } from "react";
+import { useRouter } from "next/navigation";
+import type { OnboardingTourController, OnboardingTourStep } from "@gfazioli/mantine-onboarding-tour";
+import { OnboardingTour } from "@gfazioli/mantine-onboarding-tour";
+import { Button, Center, Group, Image, Kbd, Text } from "@mantine/core";
+import type { FloatingPosition } from "@mantine/core";
+
+import { useI18n } from "@homarr/translation/client";
+
+import { homarrLogoPath } from "~/components/layout/logo/homarr-logo";
+
+interface TourShellProps extends PropsWithChildren {
+  steps: OnboardingTourStep[];
+  started: boolean;
+  onEnd: () => void;
+  stepRoutes?: Record<string, string>;
+  position?: FloatingPosition | Record<string, FloatingPosition>;
+}
+
+type TourController = OnboardingTourController;
+
+const stepIndexFromController = (controller: TourController) => controller.currentStepIndex ?? 0;
+
+const stepAtOffset = (controller: TourController, offset: number) => {
+  const index = stepIndexFromController(controller) + offset;
+  return controller.tour[index];
+};
+
+const pollForElement = (targetId: string, callback: () => void) => {
+  const interval = setInterval(() => {
+    const targetElement = document.querySelector(`[data-tour-target="${targetId}"]`);
+    if (targetElement) {
+      clearInterval(interval);
+      callback();
+    }
+  }, 50);
+  const timeout = setTimeout(() => clearInterval(interval), 5000);
+  return () => {
+    clearInterval(interval);
+    clearTimeout(timeout);
+  };
+};
+
+const isTypingTarget = (target: EventTarget | null) => {
+  if (!(target instanceof HTMLElement)) return false;
+  const tag = target.tagName;
+  return tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT" || target.isContentEditable;
+};
+
+interface TourForwardButtonProps {
+  label: string;
+  onClick: () => void;
+}
+
+const TourForwardButton = ({ label, onClick }: TourForwardButtonProps) => {
+  return (
+    <Button size="sm" variant="light" onClick={onClick} rightSection={<Kbd size="xs">↵</Kbd>}>
+      {label}
+    </Button>
+  );
+};
+
+interface TourDoneButtonProps {
+  label: string;
+  onClick: () => void;
+}
+
+const TourDoneButton = ({ label, onClick }: TourDoneButtonProps) => {
+  return (
+    <Button size="sm" onClick={onClick} rightSection={<Kbd size="xs">↵</Kbd>}>
+      {label}
+    </Button>
+  );
+};
+
+export const TourShell = ({ steps, started, onEnd, stepRoutes, position, children }: TourShellProps) => {
+  const t = useI18n();
+  const router = useRouter();
+  const forwardActionRef = useRef<(() => void) | null>(null);
+
+  const navigateAndAdvance = useCallback(
+    (currentStepId: string | undefined, targetStepId: string | undefined, advance: () => void) => {
+      if (!stepRoutes || !targetStepId) {
+        advance();
+        return;
+      }
+
+      const currentRoute = currentStepId ? stepRoutes[currentStepId] : undefined;
+      const targetRoute = stepRoutes[targetStepId];
+
+      if (targetRoute && targetRoute !== currentRoute) {
+        router.push(targetRoute);
+        pollForElement(targetStepId, advance);
+      } else {
+        advance();
+      }
+    },
+    [router, stepRoutes],
+  );
+
+  const bindForwardAction = useCallback((controller: TourController, action: () => void) => {
+    forwardActionRef.current = action;
+    return action;
+  }, []);
+
+  useEffect(() => {
+    if (!started) {
+      forwardActionRef.current = null;
+      return;
+    }
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "Enter" || event.shiftKey || event.ctrlKey || event.metaKey || event.altKey) return;
+      if (isTypingTarget(event.target)) return;
+      event.preventDefault();
+      forwardActionRef.current?.();
+    };
+
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [started]);
+
+  return (
+    <OnboardingTour
+      tour={steps}
+      started={started}
+      onOnboardingTourEnd={onEnd}
+      withStepper={false}
+      header={(controller) => (
+        <>
+          <Group justify="center" gap={4} py={4}>
+            <Text size="sm" fw={600}>
+              {stepIndexFromController(controller) + 1}
+            </Text>
+            <Text size="sm" c="dimmed">
+              /
+            </Text>
+            <Text size="sm" c="dimmed">
+              {controller.tour.length}
+            </Text>
+          </Group>
+          {stepIndexFromController(controller) === 0 && (
+            <Center py="xs">
+              <Image src={homarrLogoPath} alt="Homarr" w={64} h={64} fit="contain" />
+            </Center>
+          )}
+        </>
+      )}
+      nextStepNavigation={(controller) => {
+        const nextStep = stepAtOffset(controller, 1);
+        const action = bindForwardAction(controller, () => {
+          navigateAndAdvance(controller.currentStep?.id, nextStep?.id, () => controller.nextStep());
+        });
+        return <TourForwardButton label={t("onboardingTour.next")} onClick={action} />;
+      }}
+      endStepNavigation={(controller) => {
+        const action = bindForwardAction(controller, () => controller.endTour());
+        return <TourDoneButton label={t("onboardingTour.done")} onClick={action} />;
+      }}
+      prevStepNavigation={(controller) => (
+        <Button
+          size="sm"
+          variant="default"
+          onClick={() => {
+            const prevStep = stepAtOffset(controller, -1);
+            navigateAndAdvance(controller.currentStep?.id, prevStep?.id, () => controller.prevStep());
+          }}
+        >
+          {t("onboardingTour.prev")}
+        </Button>
+      )}
+      skipNavigation={(controller) => (
+        <Button size="sm" variant="subtle" color="gray" onClick={() => controller.skipTour()}>
+          {t("onboardingTour.skip")}
+        </Button>
+      )}
+      withPrevButton
+      focusRevealProps={{
+        disableTargetInteraction: true,
+        popoverProps: {
+          position: position ?? { base: "bottom", sm: "right" },
+          width: 420,
+          shadow: "xl",
+          radius: "lg",
+          middlewares: { shift: { padding: 16 }, flip: true },
+        },
+      }}
+      cutoutPadding={12}
+      cutoutRadius={12}
+    >
+      {children}
+    </OnboardingTour>
+  );
+};

apps/nextjs/src/components/onboarding/tour-step-content.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { Anchor, Divider, Group, Stack, Text, ThemeIcon } from "@mantine/core";
+import { IconExternalLink } from "@tabler/icons-react";
+
+import { useI18n } from "@homarr/translation/client";
+
+interface TourStepContentProps {
+  description: string;
+  documentationHref: string;
+  icon?: ReactNode;
+}
+
+export const TourStepContent = ({ description, documentationHref, icon }: TourStepContentProps) => {
+  const t = useI18n();
+
+  return (
+    <Stack gap="sm">
+      <Group gap="sm" wrap="nowrap" align="flex-start">
+        {icon && (
+          <ThemeIcon variant="light" size="lg" radius="md" mt={2}>
+            {icon}
+          </ThemeIcon>
+        )}
+        <Text size="sm" lh={1.7} style={{ flex: 1 }}>
+          {description}
+        </Text>
+      </Group>
+      <Divider />
+      <Anchor href={documentationHref} target="_blank" size="xs" fw={500}>
+        <Group gap={4} wrap="nowrap">
+          <IconExternalLink size={14} />
+          {t("onboardingTour.learnMore")}
+        </Group>
+      </Anchor>
+    </Stack>
+  );
+};