Skip to content

feat: add guided onboarding tour (WIP) #125

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
lulkebit wants to merge 2 commits into
base: dev
Choose a base branch
from
Draft

feat: add guided onboarding tour (WIP) #125

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f1dfb35
feat: add guided onboarding tour using driver.js
lulkebit Apr 20, 2026
6983091
chore: add driver.js dependency
lulkebit Apr 20, 2026
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
1,080 changes: 916 additions & 164 deletions package-lock.json
View file
Open in desktop

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
"@tauri-apps/plugin-process": "^2.3.1",
"@tauri-apps/plugin-store": "^2.4.2",
"@tauri-apps/plugin-updater": "^2.10.1",
"driver.js": "^1.4.0",
"react": "^19.2.4",
"react-dom": "^19.2.4"
},
Expand Down
22 changes: 22 additions & 0 deletions src/App.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ const AdvancedPanel = lazy(
);
const SettingsPanel = lazy(() => import("./components/panels/SettingsPanel"));
const TitleBar = lazy(() => import("./components/TitleBar"));
const OnboardingTour = lazy(() => import("./components/OnboardingTour"));
export type Tab = "simple" | "advanced" | "settings";

const BACKEND_SETTINGS_SCHEMA_VERSION = 8;
Expand Down Expand Up @@ -125,6 +126,7 @@ export default function App() {
currentVersion: string;
latestVersion: string;
} | null>(null);
const [tourActive, setTourActive] = useState(false);

const hotkeyTimer = useRef<number | null>(null);
const hotkeyRequestIdRef = useRef(0);
Expand Down Expand Up @@ -502,6 +504,10 @@ export default function App() {
setStatus(loadedStatus);
setSettingsLoaded(true);

if (!hydratedSettings.onboardingCompleted) {
setTourActive(true);
}

await syncSettingsToBackend(hydratedSettings);

if (
Expand Down Expand Up @@ -695,6 +701,16 @@ export default function App() {
}
};

const handleTourComplete = () => {
setTourActive(false);
updateSettings({ onboardingCompleted: true });
};

const handleStartTour = () => {
setTourActive(false);
requestAnimationFrame(() => setTourActive(true));
};

const handlePickPosition = async () => {
try {
const point = await invoke<{ x: number; y: number }>("pick_position");
Expand All @@ -712,6 +728,11 @@ export default function App() {
return (
<I18nProvider language={settings.language}>
<div className="app-root" data-tab={tab}>
<OnboardingTour
active={tourActive}
onComplete={handleTourComplete}
setTab={handleTabChange}
/>
<TitleBar
tab={tab}
setTab={handleTabChange}
Expand Down Expand Up @@ -757,6 +778,7 @@ export default function App() {
onDeletePreset={handleDeletePreset}
onToggleAlwaysOnTop={handleToggleAlwaysOnTop}
onReset={handleResetSettings}
onStartTour={handleStartTour}
/>
)}
</main>
Expand Down
130 changes: 130 additions & 0 deletions src/components/OnboardingTour.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
/* ── Overlay ─────────────────────────────────────────────────────────────── */
.driver-overlay {
z-index: 9998 !important;
}

/* ── Popover container ───────────────────────────────────────────────────── */
.driver-popover.onboarding-popover {
background: var(--bg-elevated);
border: 1px solid var(--border);
border-radius: var(--radius-lg);
color: var(--text-primary);
font-family: var(--font-family-base);
box-shadow:
0 8px 24px rgba(0, 0, 0, 0.45),
0 2px 6px rgba(0, 0, 0, 0.3);
max-width: 320px;
min-width: 260px;
padding: 1.25rem 1.25rem 1rem;
z-index: 9999 !important;
}

/* ── Arrow ───────────────────────────────────────────────────────────────── */
.driver-popover.onboarding-popover.driver-popover-arrow-side-top::before {
border-top-color: var(--bg-elevated) !important;
}
.driver-popover.onboarding-popover.driver-popover-arrow-side-bottom::before {
border-bottom-color: var(--bg-elevated) !important;
}
.driver-popover.onboarding-popover.driver-popover-arrow-side-left::before {
border-left-color: var(--bg-elevated) !important;
}
.driver-popover.onboarding-popover.driver-popover-arrow-side-right::before {
border-right-color: var(--bg-elevated) !important;
}

/* ── Title ───────────────────────────────────────────────────────────────── */
.driver-popover.onboarding-popover .driver-popover-title {
color: var(--text-primary);
font-size: 0.9375rem;
font-weight: var(--font-weight-hv);
margin-bottom: 0.5rem;
padding-right: 1.25rem; /* leave room for close btn */
}

/* ── Description ─────────────────────────────────────────────────────────── */
.driver-popover.onboarding-popover .driver-popover-description {
color: var(--text-muted);
font-size: 0.8125rem;
line-height: 1.55;
margin-bottom: 0;
}

/* ── Close button ────────────────────────────────────────────────────────── */
.driver-popover.onboarding-popover .driver-popover-close-btn {
position: absolute;
top: 0.75rem;
right: 0.75rem;
background: transparent;
border: none;
color: var(--text-dim);
cursor: pointer;
font-size: 1rem;
line-height: 1;
padding: 2px 4px;
border-radius: var(--radius-sm);
transition: color 0.15s ease;
z-index: 1;
}
.driver-popover.onboarding-popover .driver-popover-close-btn:hover {
color: var(--text-primary);
}

/* ── Footer ──────────────────────────────────────────────────────────────── */
.driver-popover.onboarding-popover .driver-popover-footer {
display: flex;
align-items: center;
justify-content: flex-end;
gap: 0.5rem;
margin-top: 1rem;
}

/* ── Progress text ───────────────────────────────────────────────────────── */
.driver-popover.onboarding-popover .driver-popover-progress-text {
color: var(--text-dim);
font-size: 0.75rem;
font-weight: var(--font-weight-md);
margin-right: auto;
}

/* ── Shared button base ──────────────────────────────────────────────────── */
.driver-popover.onboarding-popover .driver-popover-prev-btn,
.driver-popover.onboarding-popover .driver-popover-next-btn {
background: var(--bg-input);
color: var(--text-primary);
border: 1px solid var(--border);
border-radius: var(--radius-sm);
padding: 0.3125rem 0.875rem;
font-size: 0.8rem;
font-weight: var(--font-weight-md);
font-family: var(--font-family-base);
cursor: pointer;
line-height: 1.4;
transition:
background 0.15s ease,
border-color 0.15s ease,
filter 0.15s ease;
white-space: nowrap;
}

/* ── Next / Done button: accent-colored ─────────────────────────────────── */
.driver-popover.onboarding-popover .driver-popover-next-btn {
background: var(--accent-green-strong);
border-color: transparent;
color: #fff;
}

.driver-popover.onboarding-popover .driver-popover-prev-btn:hover {
background: var(--bg-input-off);
border-color: var(--border-focus);
}
.driver-popover.onboarding-popover .driver-popover-next-btn:hover {
filter: brightness(1.12);
}

/* ── Highlighted element ring ────────────────────────────────────────────── */
.driver-active .driver-active-element {
outline: 2px solid var(--accent-green) !important;
outline-offset: 3px !important;
border-radius: var(--radius-sm) !important;
}
Loading
Loading