Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions apps/desktop/src/components/CommandPalette.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ import {
ChevronIcon,
FolderIcon,
GlobeIcon,
HelpIcon,
KeyboardIcon,
LinkIcon,
PlayIcon,
Expand Down Expand Up @@ -183,6 +184,8 @@ function ItemIcon({ icon }: { icon: PaletteIcon }) {
return <KeyboardIcon size={13} />;
case "agents":
return <LinkIcon size={13} />;
case "help":
return <HelpIcon size={13} />;
case "play":
case "restart":
return <PlayIcon size={11} />;
Expand Down
14 changes: 9 additions & 5 deletions apps/desktop/src/components/GetStarted.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,11 @@ import {
type ChecklistItem,
checklistItems,
hasRunningService,
hideChecklist,
isAnyAgentConnected,
isChecklistShown,
updateOnboarding,
useIsChecklistReplayed,
useOnboarding,
} from "../onboarding";
import { showSheet, useUi } from "../ui";
Expand All @@ -25,10 +27,12 @@ type Props = {
/**
* The Get started checklist, at the foot of the sidebar once there is a
* Project: each row ticks from what is true, an open row takes the user
* there. It goes away for good when every row is ticked or it is closed.
* there. It goes away for good when every row is ticked or it is closed;
* shown again from Help, it stays until closed.
*/
export function GetStarted({ view, selectedProjectId, onSelectProject }: Props) {
const onboarding = useOnboarding();
const isReplayed = useIsChecklistReplayed();
const isShown = onboarding !== null && isChecklistShown(onboarding, view);
const hasConnectedAgent = useHasConnectedAgent(isShown);
const isRunning = hasRunningService(view);
Expand All @@ -39,10 +43,10 @@ export function GetStarted({ view, selectedProjectId, onSelectProject }: Props)
if (isShown && isRunning && !onboarding?.hasStartedService) updateOnboarding({ hasStartedService: true });
}, [isShown, isRunning, onboarding]);
useEffect(() => {
if (isShown && isComplete) updateOnboarding({ isChecklistDone: true });
}, [isShown, isComplete]);
if (isShown && isComplete && !isReplayed) updateOnboarding({ isChecklistDone: true });
}, [isShown, isComplete, isReplayed]);

if (!isShown || isComplete) return null;
if (!isShown || (isComplete && !isReplayed)) return null;
const doneCount = items.filter((item) => item.isDone).length;
const act = (item: ChecklistItem) => {
if (item.step === "agents") {
Expand Down Expand Up @@ -70,7 +74,7 @@ export function GetStarted({ view, selectedProjectId, onSelectProject }: Props)
className={styles.close}
aria-label="Hide Get Started"
title="Hide Get Started"
onClick={() => updateOnboarding({ isChecklistDone: true })}
onClick={hideChecklist}
>
<ClearIcon size={13} />
</button>
Expand Down
8 changes: 8 additions & 0 deletions apps/desktop/src/components/Icons.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -255,6 +255,14 @@ export const CheckIcon = (props: Props) => (
</Icon>
);

/** `questionmark.circle`: Help. */
export const HelpIcon = (props: Props) => (
<Icon {...props} strokeWidth={1.2}>
<circle cx="8" cy="8" r="6.5" />
<path d="M6.2 6.2a1.9 1.9 0 0 1 3.7.5c0 1.3-1.9 1.6-1.9 2.8M8 11.6h.01" />
</Icon>
);

/** `keyboard`: Keyboard Shortcuts. */
export const KeyboardIcon = (props: Props) => (
<Icon {...props} strokeWidth={1.2}>
Expand Down
6 changes: 6 additions & 0 deletions apps/desktop/src/components/Menu.module.css
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,12 @@
right: 0;
}

.above {
position: absolute;
bottom: calc(100% + 4px);
right: 0;
}

.alignLeft {
right: auto;
left: 0;
Expand Down
6 changes: 4 additions & 2 deletions apps/desktop/src/components/Menu.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,12 @@ type Props = {
button?: { content: ReactNode; className: string };
/** Which side of the button the menu lines up with. */
align?: "left" | "right";
/** Opens upward, for a button at the foot of the window. */
isAbove?: boolean;
};

/** A button opening a menu: by default a borderless `⋯`, for rare actions. */
export function Menu({ label, items, button: custom, align = "right" }: Props) {
export function Menu({ label, items, button: custom, align = "right", isAbove = false }: Props) {
const [isOpen, setIsOpen] = useState(false);
const button = useRef<HTMLButtonElement>(null);
const menuId = useId();
Expand All @@ -44,7 +46,7 @@ export function Menu({ label, items, button: custom, align = "right" }: Props) {
id={menuId}
label={label}
items={items}
className={`${styles.below} ${align === "left" ? styles.alignLeft : ""}`}
className={`${isAbove ? styles.above : styles.below} ${align === "left" ? styles.alignLeft : ""}`}
onClose={(returnFocus) => {
setIsOpen(false);
if (returnFocus) button.current?.focus();
Expand Down
54 changes: 53 additions & 1 deletion apps/desktop/src/components/Onboarding.test.tsx
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
import { act, fireEvent, render, screen, waitFor } from "@testing-library/react";
import { afterEach, describe, expect, it, vi } from "vitest";
import { viewFromSnapshot } from "../core";
import { resetOnboarding, startOnboarding } from "../onboarding";
import { resetOnboarding, showChecklistAgain, startOnboarding } from "../onboarding";
import { project, service, status } from "../test/fixtures";
import { currentUi, resetUi } from "../ui";
import { GetStarted } from "./GetStarted";
import { helpMenuItems } from "./Sidebar";
import { Welcome } from "./Welcome";

const commands = vi.hoisted(() => ({
Expand Down Expand Up @@ -94,3 +95,54 @@ describe("GetStarted", () => {
expect(container.innerHTML).toBe("");
});
});

describe("Help", () => {
const shop = project("Shop", 0, [service("Web")]);
const used = { hasSeenWelcome: true, isChecklistDone: true, hasStartedService: true };
const help = (label: string) => {
const item = helpMenuItems().find((item) => item !== "separator" && item.label === label);
if (!item || item === "separator") throw new Error(`no ${label}`);
return item;
};

it("shows the welcome again with Projects present, and leaves the saved state as it was", async () => {
commands.onboarding.mockResolvedValue({ onboarding: used, hasOpenedBefore: true });
await act(() => startOnboarding(1));
act(() => help("Show Welcome…").onSelect());
expect(currentUi().sheet).toEqual({ kind: "welcome" });

render(<Welcome />);
fireEvent.click(screen.getByRole("button", { name: "Skip" }));
expect(currentUi().sheet).toBeNull();
expect(commands.saveOnboarding).not.toHaveBeenCalled();
});

it("brings back the checklist, ticked from what is true, until closed again", async () => {
commands.onboarding.mockResolvedValue({ onboarding: used, hasOpenedBefore: true });
commands.agentStatuses.mockResolvedValue([{ connection: "connected" }]);
await act(() => startOnboarding(1));
const view = viewFromSnapshot({ projects: [shop], statuses: [status(shop.services[0].id, "running")], projectStates: [] });
const { container } = render(<GetStarted view={view} selectedProjectId={null} onSelectProject={vi.fn()} />);
expect(container.innerHTML).toBe("");

act(() => help("Show Get Started Checklist").onSelect());
expect(commands.saveOnboarding).toHaveBeenLastCalledWith({ ...used, isChecklistDone: false });
// Every row is ticked, yet it stays: it was asked for.
await waitFor(() => expect(screen.getByText("4 of 4")).toBeTruthy());
await act(() => new Promise((resolve) => setTimeout(resolve, 0)));
expect(screen.getByText("4 of 4")).toBeTruthy();

fireEvent.click(screen.getByRole("button", { name: "Hide Get Started" }));
expect(container.innerHTML).toBe("");
expect(commands.saveOnboarding).toHaveBeenLastCalledWith(used);
});

it("shows a closed checklist again even before it was complete", async () => {
commands.onboarding.mockResolvedValue({ onboarding: { ...used, hasStartedService: false }, hasOpenedBefore: true });
await act(() => startOnboarding(1));
const view = viewFromSnapshot({ projects: [shop], statuses: [], projectStates: [] });
render(<GetStarted view={view} selectedProjectId={null} onSelectProject={vi.fn()} />);
act(() => showChecklistAgain());
expect(screen.getByText("2 of 4")).toBeTruthy();
});
});
35 changes: 24 additions & 11 deletions apps/desktop/src/components/Sidebar.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,11 @@ import { importProject } from "../editors";
import { SHORTCUTS, shortcutLabel } from "../keyboard";
import type { ShownMachine } from "../machines";
import { isActive, projectServicesSummary } from "../status";
import { showChecklistAgain } from "../onboarding";
import { showAlert, showSheet } from "../ui";
import { useUpdate } from "../updates";
import { GetStarted } from "./GetStarted";
import { ClearIcon, GearIcon, GlobeIcon, KeyboardIcon, PlusIcon, SearchIcon } from "./Icons";
import { ClearIcon, GearIcon, GlobeIcon, HelpIcon, PlusIcon, SearchIcon } from "./Icons";
import { Menu, type MenuItem, useContextMenu } from "./Menu";
import { projectMenuItems } from "./ServicesColumn";
import { ShortcutBadge } from "./ShortcutBadge";
Expand All @@ -29,8 +30,8 @@ type Props = {

/**
* The wordmark and project search, Ports and the Projects, then each other
* Machine's, a newer version when there is one, and a footer with Settings
* and how many Services run.
* Machine's, a newer version when there is one, and a footer with Settings,
* Help and how many Services run.
*/
export function Sidebar({ view, machines = [], selection, onSelect }: Props) {
const [search, setSearch] = useState("");
Expand Down Expand Up @@ -167,21 +168,33 @@ export function Sidebar({ view, machines = [], selection, onSelect }: Props) {
>
<GearIcon size={15} />
</button>
<button
className="iconButton"
aria-label="Keyboard Shortcuts"
title={`Keyboard Shortcuts (${shortcutLabel(SHORTCUTS.keyboardShortcuts)})`}
onClick={() => showAlert({ kind: "keyboardShortcuts" })}
>
<KeyboardIcon size={15} />
</button>
<Menu
label="Help"
items={helpMenuItems()}
button={{ content: <HelpIcon size={15} />, className: "iconButton" }}
align="left"
isAbove
/>
</div>
{running > 0 && <span className={`${styles.running} mono secondary`}>{running} running</span>}
</footer>
</nav>
);
}

/**
* The macOS app's Help menu, as this window has no menu bar: Keyboard
* Shortcuts, and the first run's welcome and checklist on request.
*/
export function helpMenuItems(): MenuItem[] {
return [
{ label: "Keyboard Shortcuts", onSelect: () => showAlert({ kind: "keyboardShortcuts" }) },
"separator",
{ label: "Show Welcome…", onSelect: () => showSheet({ kind: "welcome" }) },
{ label: "Show Get Started Checklist", onSelect: showChecklistAgain },
];
}

type ProjectRowProps = {
project: Project;
view: CoreView;
Expand Down
2 changes: 1 addition & 1 deletion apps/desktop/src/components/Welcome.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ import styles from "./Welcome.module.css";
/**
* The first launch's welcome: what a Project, a Service and a Port are, one
* step each, ending in Add Project…. Skipping, Escape or finishing all
* mean it never opens again.
* mean it never opens by itself again; Help › Show Welcome… opens it anyway.
*/
export function Welcome() {
const [index, setIndex] = useState(0);
Expand Down
46 changes: 38 additions & 8 deletions apps/desktop/src/onboarding.ts
Original file line number Diff line number Diff line change
Expand Up @@ -92,11 +92,18 @@ export function isAnyAgentConnected(agents: readonly AgentStatus[]): boolean {
// so nothing shows before then.

let current: Onboarding | null = null;
// The checklist was asked for again from Help: it stays until closed, even
// with every row ticked. Not saved, so the next launch is as before.
let isChecklistReplayed = false;
const listeners = new Set<() => void>();

function notify() {
listeners.forEach((listener) => listener());
}

function publish(next: Onboarding) {
current = next;
listeners.forEach((listener) => listener());
notify();
}

/** At launch, once the Projects are known: whether to open the welcome. */
Expand All @@ -118,17 +125,40 @@ export function updateOnboarding(change: Partial<Onboarding>) {
void commands.saveOnboarding(next);
}

/**
* Help › Show Get Started Checklist: brings the checklist back after it was
* closed or completed. Its rows still tick from what is true.
*/
export function showChecklistAgain() {
if (!current) return;
isChecklistReplayed = true;
if (current.isChecklistDone) updateOnboarding({ isChecklistDone: false });
else notify();
}

/** The checklist's close button: gone until asked for again. */
export function hideChecklist() {
isChecklistReplayed = false;
updateOnboarding({ isChecklistDone: true });
notify();
}

function subscribe(listener: () => void) {
listeners.add(listener);
return () => void listeners.delete(listener);
}

export function useOnboarding(): Onboarding | null {
return useSyncExternalStore(
(listener) => {
listeners.add(listener);
return () => listeners.delete(listener);
},
() => current,
);
return useSyncExternalStore(subscribe, () => current);
}

/** Whether the checklist was asked for again, so a complete one stays until closed. */
export function useIsChecklistReplayed(): boolean {
return useSyncExternalStore(subscribe, () => isChecklistReplayed);
}

/** For tests. */
export function resetOnboarding() {
current = null;
isChecklistReplayed = false;
}
11 changes: 11 additions & 0 deletions apps/desktop/src/palette.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -61,4 +61,15 @@ describe("palette", () => {
item.run();
expect(currentUi().sheet).toEqual({ kind: "connectAgents" });
});

it("offers Show Welcome… and Show Get Started Checklist when typed for", () => {
resetUi();
const items = paletteItems(view, shop, { kind: "all" }, navigator);
const welcome = items.find((item) => item.title === "Show Welcome…")!;
const checklist = items.find((item) => item.title === "Show Get Started Checklist")!;
expect(welcome.id.startsWith("other:")).toBe(true);
expect(checklist.id.startsWith("other:")).toBe(true);
welcome.run();
expect(currentUi().sheet).toEqual({ kind: "welcome" });
});
});
17 changes: 16 additions & 1 deletion apps/desktop/src/palette.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import { projectShortcut, SHORTCUTS, type Shortcut, serviceShortcut, shortcutLab
import { tildePath } from "./paths";
import type { ServiceSelection } from "./selection";
import { isActive } from "./status";
import { showChecklistAgain } from "./onboarding";
import { showAlert, showSheet } from "./ui";
import { checkForUpdates } from "./updates";

Expand All @@ -19,7 +20,7 @@ export type Navigator = {
};

export type PaletteIcon =
| { kind: "symbol"; name: "folder" | "service" | "play" | "stop" | "restart" | "browser" | "terminal" | "editor" | "ports" | "new" | "keyboard" | "agents" }
| { kind: "symbol"; name: "folder" | "service" | "play" | "stop" | "restart" | "browser" | "terminal" | "editor" | "ports" | "new" | "keyboard" | "agents" | "help" }
/** A Service: its colour (by position) and state glyph. */
| { kind: "service"; index: number; state: ServiceState };

Expand Down Expand Up @@ -98,6 +99,20 @@ export function paletteItems(
keywords: "mcp claude cursor codex agent skill path terminal cli",
run: () => showSheet({ kind: "connectAgents" }),
});
items.push({
id: "other:show-welcome",
title: "Show Welcome…",
icon: { kind: "symbol", name: "help" },
keywords: "help onboarding introduction tour first run",
run: () => showSheet({ kind: "welcome" }),
});
items.push({
id: "other:show-checklist",
title: "Show Get Started Checklist",
icon: { kind: "symbol", name: "help" },
keywords: "help onboarding get started first run",
run: showChecklistAgain,
});
items.push({
id: "other:check-for-updates",
title: "Check for Updates…",
Expand Down
2 changes: 1 addition & 1 deletion apps/desktop/src/ui.ts
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ export type Sheet =
| { kind: "importProject"; file: string; preview: ImportPreview }
/** Connect your agents: Claude Code, Cursor and Codex, and the command in terminals. */
| { kind: "connectAgents" }
/** The first launch's welcome, ending in Add Project…. */
/** The first launch's welcome, ending in Add Project…; also Help › Show Welcome…. */
| { kind: "welcome" };

/** The UI's own state, outside the core. */
Expand Down
Loading
Loading