π OpenHands: AI-Driven Development
import {
type MouseEvent,
type ReactNode,
useCallback,
useEffect,
useRef,
useState,
useSyncExternalStore,
} from "react";
import { useTranslation } from "react-i18next";
import { ArrowUpRight, Check, ClipboardList, X } from "lucide-react";
import { getLockedCloudHost } from "#/api/agent-server-config";
import { ConfirmationModal } from "#/components/shared/modals/confirmation-modal";
import { NavigationLink } from "#/components/shared/navigation-link";
import { useNavigation } from "#/context/navigation-context";
import { useActiveBackend } from "#/contexts/active-backend-context";
import { I18nKey } from "#/i18n/declaration";
import { formControlButtonClassName } from "#/utils/form-control-classes";
import { cn } from "#/utils/utils";
import {
SETUP_TOUR_PARAM,
SUPER_ADMIN_SETUP_GUIDE_PAGE_PATH,
SUPER_ADMIN_SETUP_STEPS,
type SuperAdminSetupStep,
type SuperAdminSetupStepId,
} from "./super-admin-setup-guide.constants";
import { SUPER_ADMIN_SETUP_STEP_EVENT } from "./super-admin-setup-step-event";
import {
hasSetupGuideTour,
startSetupGuideTour,
} from "./tour/setup-guide-tour";
import {
isGuidedTourActive,
subscribeGuidedTourActive,
} from "./tour/tour-engine";
import {
getNextSetupStep,
useSuperAdminSetupGuide,
} from "./use-super-admin-setup-guide";
const ICON_BUTTON_CLASS = cn(
"inline-flex size-7 shrink-0 items-center justify-center rounded-md",
"text-muted hover:bg-surface hover:text-contrast",
);
const STEP_ROW_CLASS =
"flex w-full min-w-0 items-center gap-2.5 rounded-md px-2.5 py-1.5 hover:bg-surface";
// The enterprise guide's primary button: light on dark. Canvas's `primary`
// is its gold accent, so this uses `foreground` like the enterprise app.
const START_BUTTON_CLASS = cn(
formControlButtonClassName,
"w-full bg-foreground font-medium text-on-primary hover:opacity-80",
);
const START_TEST_ID = "super-admin-setup-guide-start";
/**
* A page on the cloud host, on the guide's organization when given, and
* naming the step whose tour the enterprise guide should start.
*/
function cloudPageUrl(
cloudHost: string,
path: string,
orgId: string | null,
tourStepId?: SuperAdminSetupStepId,
) {
const params = new URLSearchParams();
if (orgId) params.set("org", orgId);
if (tourStepId) params.set(SETUP_TOUR_PARAM, tourStepId);
const query = params.toString();
return query ? `${cloudHost}${path}?${query}` : `${cloudHost}${path}`;
}
/**
* Floating lower-right setup guide for the enterprise Super Admin, matching
* the guide in the OpenHands Enterprise app. Steps that live in the
* enterprise app link back to it; progress is read from the server.
*/
export default function SuperAdminSetupGuide() {
const { t } = useTranslation("openhands");
const { currentPath, navigate } = useNavigation();
const { backend } = useActiveBackend();
const {
steps,
completedCount,
totalCount,
nextStep,
guideOrgId,
visible,
refetch,
dismiss,
} = useSuperAdminSetupGuide();
const [open, setOpen] = useState(true);
const [confirmDismiss, setConfirmDismiss] = useState(false);
const tourActive = useSyncExternalStore(
subscribeGuidedTourActive,
isGuidedTourActive,
isGuidedTourActive,
);
// The tour checks the current route after it navigates, between renders.
const pathRef = useRef(currentPath);
useEffect(() => {
pathRef.current = currentPath;
}, [currentPath]);
const startTour = useCallback(
(stepId: SuperAdminSetupStepId) =>
startSetupGuideTour(
stepId,
{ navigate, getPath: () => pathRef.current },
t,
),
[navigate, t],
);
// Progress is read from the server, so re-read it as the admin moves around.
useEffect(() => {
if (visible) {
refetch();
}
}, [currentPath, visible, refetch]);
const cloudHost = backend.host.replace(/\/+$/, "");
// Locked-to-Cloud serves the canvas on the cloud host itself, so enterprise
// pages open in this tab; standalone / Electron keep a new tab.
const isLockedToCloud = getLockedCloudHost() !== null;
// When the guide's next step is done, open the step after it the way Start
// does. A step finished out of order, or not confirmed by the server, only
// refreshes the progress; nothing opens after the last required step.
const nextStepId = nextStep?.id ?? null;
useEffect(() => {
if (!visible) {
return undefined;
}
const onStep = async (event: Event) => {
const completedId = (event as CustomEvent<{ id?: string }>).detail?.id;
const { data } = await refetch();
const guideSteps = data?.guide_steps;
if (!guideSteps || !completedId || completedId !== nextStepId) {
return;
}
const after = getNextSetupStep(guideSteps);
if (!after || after.id === completedId) {
return;
}
const { destination } = after;
if (destination.kind === "canvas") {
if (hasSetupGuideTour(after.id)) {
await startTour(after.id);
} else {
navigate(destination.path);
}
} else if (isLockedToCloud) {
window.location.assign(
cloudPageUrl(
cloudHost,
destination.path,
destination.withOrg ? guideOrgId : null,
after.id,
),
);
} else {
// A new tab opened after a save is blocked, so point at Start instead.
setOpen(true);
}
};
window.addEventListener(SUPER_ADMIN_SETUP_STEP_EVENT, onStep);
return () =>
window.removeEventListener(SUPER_ADMIN_SETUP_STEP_EVENT, onStep);
}, [
visible,
refetch,
nextStepId,
navigate,
startTour,
cloudHost,
guideOrgId,
isLockedToCloud,
]);
// A page opened from the enterprise guide names the step whose tour to
// start. Enterprise steps have no tour here, so only Canvas steps start.
useEffect(() => {
if (!visible) {
return;
}
const params = new URLSearchParams(window.location.search);
const requested = params.get(SETUP_TOUR_PARAM);
if (!requested) {
return;
}
// Drop it first, so the tour starts once.
params.delete(SETUP_TOUR_PARAM);
const query = params.toString();
window.history.replaceState(
window.history.state,
"",
`${window.location.pathname}${query ? `?${query}` : ""}${window.location.hash}`,
);
const step = SUPER_ADMIN_SETUP_STEPS.find(({ id }) => id === requested);
if (step && hasSetupGuideTour(step.id)) {
setOpen(false);
startTour(step.id);
}
}, [visible, startTour]);
if (!visible || tourActive) {
return null;
}
const cloudLinkProps = {
target: isLockedToCloud ? undefined : "_blank",
rel: isLockedToCloud ? undefined : "noopener noreferrer",
};
const cloudUrl = (
path: string,
withOrg: boolean,
tourStepId?: SuperAdminSetupStepId,
) => cloudPageUrl(cloudHost, path, withOrg ? guideOrgId : null, tourStepId);
// A plain click on a Canvas step that has a tour runs the tour, which opens
// the step's page itself; a modified click still follows the link.
const startStepTour = (
step: SuperAdminSetupStep,
event: MouseEvent<HTMLAnchorElement>,
) => {
const plainClick =
event.button === 0 &&
!event.metaKey &&
!event.ctrlKey &&
!event.shiftKey &&
!event.altKey;
if (
plainClick &&
step.destination.kind === "canvas" &&
hasSetupGuideTour(step.id)
) {
event.preventDefault();
setOpen(false);
startTour(step.id);
}
};
// A step row and Start open the same page for a step, with the step's tour
// for a Canvas step. Start also asks the enterprise guide for its tour.
const renderStepLink = (
step: SuperAdminSetupStep,
testId: string,
className: string,
children: ReactNode,
onClick?: (event: MouseEvent<HTMLAnchorElement>) => void,
startsTour = false,
) =>
step.destination.kind === "canvas" ? (
<NavigationLink
to={step.destination.path}
data-testid={testId}
className={className}
onClick={onClick}
>
{children}
</NavigationLink>
) : (
<a
href={cloudUrl(
step.destination.path,
step.destination.withOrg,
startsTour ? step.id : undefined,
)}
{...cloudLinkProps}
data-testid={testId}
className={className}
onClick={onClick}
>
{children}
</a>
);
const title = t(I18nKey.ONBOARDING$SETUP_GUIDE_TITLE);
const progressPct = Math.round((completedCount / totalCount) * 100);
return (
<div
className="fixed bottom-5 right-5 z-30 flex flex-col items-end gap-2"
data-testid="super-admin-setup-guide"
>
{open ? (
<div
data-testid="super-admin-setup-guide-panel"
className={cn(
"flex w-80 flex-col gap-3 rounded-xl border border-border",
"bg-surface-raised p-4 shadow-lg",
)}
>
<div className="flex items-center justify-between gap-2">
<p className="min-w-0 text-sm font-semibold text-content">
{title}
</p>
<div className="flex shrink-0 items-center gap-0.5">
<a
href={cloudUrl(SUPER_ADMIN_SETUP_GUIDE_PAGE_PATH, false)}
{...cloudLinkProps}
data-testid="super-admin-setup-guide-page"
aria-label={title}
title={title}
className={ICON_BUTTON_CLASS}
>
<ArrowUpRight className="size-4" strokeWidth={2} aria-hidden />
</a>
<button
type="button"
aria-label={t(I18nKey.BUTTON$CLOSE)}
className={ICON_BUTTON_CLASS}
// Closing asks whether to turn the guide off for good;
// cancelling leaves it closed to the pill.
onClick={() => {
setOpen(false);
setConfirmDismiss(true);
}}
>
<X className="size-4" strokeWidth={2} aria-hidden />
</button>
</div>
</div>
<div className="flex items-center gap-3">
<div
className="h-1.5 flex-1 overflow-hidden rounded-full bg-border"
role="progressbar"
aria-valuemin={0}
aria-valuemax={100}
aria-valuenow={progressPct}
aria-label={title}
>
<div
className="h-full rounded-full bg-foreground transition-all duration-300"
style={{ width: `${progressPct}%` }}
/>
</div>
<span className="shrink-0 text-xs tabular-nums text-muted">
{completedCount}/{totalCount}
</span>
</div>
<ul className="flex flex-col gap-0.5">
{steps.map((step) => {
const label = (
<>
<span
aria-hidden
className={cn(
"inline-flex size-4 shrink-0 items-center justify-center rounded-full border",
step.done
? "border-foreground bg-foreground text-on-primary"
: "border-border bg-transparent",
)}
>
{step.done ? (
<Check className="size-2.5" strokeWidth={3} />
) : null}
</span>
<span
className={cn(
"min-w-0 flex-1 truncate text-xs",
step.done ? "text-muted line-through" : "text-content",
)}
>
{t(step.labelKey)}
</span>
</>
);
const testId = `super-admin-setup-guide-step-${step.id}`;
const rowClassName = cn(
STEP_ROW_CLASS,
nextStep?.id === step.id && "bg-surface",
);
return (
<li key={step.id}>
{renderStepLink(step, testId, rowClassName, label, (event) =>
startStepTour(step, event),
)}
</li>
);
})}
</ul>
{nextStep ? (
<div className="flex flex-col gap-2">
<p
className="text-xs text-muted"
data-testid="super-admin-setup-guide-next"
>
{t(I18nKey.ONBOARDING$SETUP_GUIDE_NEXT, {
step: t(nextStep.labelKey),
})}
</p>
{/* Like the enterprise Start, close the panel before opening
the step, so Start does something even when the admin is
already on that step's page. */}
{renderStepLink(
nextStep,
START_TEST_ID,
START_BUTTON_CLASS,
t(I18nKey.ONBOARDING$SETUP_GUIDE_START),
(event) => {
setOpen(false);
startStepTour(nextStep, event);
},
true,
)}
</div>
) : null}
</div>
) : null}
<button
type="button"
data-testid="super-admin-setup-guide-toggle"
aria-label={title}
aria-expanded={open}
onClick={() => setOpen((current) => !current)}
className={cn(
"flex items-center gap-2 rounded-full border border-border",
"bg-surface-raised px-3.5 py-2 text-sm font-medium text-content",
"shadow-sm hover:bg-surface",
)}
>
<ClipboardList className="size-4" strokeWidth={2} aria-hidden />
{title}
</button>
{confirmDismiss ? (
<ConfirmationModal
text={t(I18nKey.ONBOARDING$SETUP_GUIDE_DISMISS_CONFIRM)}
onConfirm={() => {
setConfirmDismiss(false);
dismiss();
}}
onCancel={() => setConfirmDismiss(false)}
/>
) : null}
</div>
);
}