Refine onboarding based on maintainer review conventions

Author: iammajid

frontend/public/cryptomator.svg frontend/public/app-logo.svgfrontend/public/cryptomator.svg renamed to frontend/public/app-logo.svg

@@ -1,12 +1,17 @@
 export function isMobile(): boolean {
-  return /android|iphone|ipad|ipod/i.test(navigator.userAgent);
+  return /android|iphone|ipad|ipod/i.test(navigator.userAgent) || isIpadOs();
+}
+
+// iPadOS reports itself as a Mac in the user agent; the touch screen gives it away
+function isIpadOs(): boolean {
+  return /mac/i.test(navigator.userAgent) && navigator.maxTouchPoints > 1;
 }
 
 export function appDownloadUrl(): string {
   const ua = navigator.userAgent;
   if (/android/i.test(ua)) {
     return 'https://play.google.com/store/apps/details?id=org.cryptomator.freemium';
-  } else if (/iphone|ipad|ipod/i.test(ua)) {
+  } else if (/iphone|ipad|ipod/i.test(ua) || isIpadOs()) {
     return 'https://apps.apple.com/app/cryptomator/id1560822163';
   } else if (/windows/i.test(ua)) {
     return 'https://cryptomator.org/downloads/win/thanks/';
@@ -24,13 +29,14 @@ let cachedMacDownloadUrl: string | undefined;
 const macFallbackUrl = 'https://cryptomator.org/downloads/#mac';
 
 // same WebGL renderer sniffing as cryptomator.org uses to tell Apple Silicon and Intel Macs apart;
-// cached because every sniff allocates a WebGL context that counts against the browser's context cap
+// the context is released right away and the result cached, as browsers cap concurrent WebGL contexts
 function macDownloadUrl(): string {
   try {
     const gl = document.createElement('canvas').getContext('webgl');
     if (gl) {
       const info = gl.getExtension('WEBGL_debug_renderer_info');
       const renderer = info ? String(gl.getParameter(info.UNMASKED_RENDERER_WEBGL)).toLowerCase() : '';
+      gl.getExtension('WEBGL_lose_context')?.loseContext();
       cachedMacDownloadUrl = macUrlForRenderer(renderer);
       return cachedMacDownloadUrl;
     }
@@ -49,24 +55,3 @@ function macUrlForRenderer(renderer: string): string {
     return macFallbackUrl;
   }
 }
-
-function appHintKey(userId: string): string {
-  return `hub.appHintDismissed.${userId}`;
-}
-
-export function isAppHintDismissed(userId: string): boolean {
-  try {
-    return localStorage.getItem(appHintKey(userId)) !== null;
-  } catch {
-    // without localStorage we cannot remember a dismissal, so rather hide the hint than repeat it on every visit
-    return true;
-  }
-}
-
-export function dismissAppHint(userId: string) {
-  try {
-    localStorage.setItem(appHintKey(userId), new Date().toISOString());
-  } catch {
-    // if localStorage is unavailable, the hint may show again next time
-  }
-}

frontend/src/common/appdownload.ts

@@ -1,5 +1,5 @@
 import { DriveStep, driver } from 'driver.js';
-import { createApp } from 'vue';
+import { createApp, ref } from 'vue';
 import type { App, Component } from 'vue';
 import GetAppStep from '../components/onboarding/GetAppStep.vue';
 import ProfileVignette from '../components/onboarding/ProfileVignette.vue';
@@ -8,30 +8,43 @@ import VaultListVignette from '../components/onboarding/VaultListVignette.vue';
 import WelcomeVignette from '../components/onboarding/WelcomeVignette.vue';
 import i18n from '../i18n';
 import auth from './auth';
+import { isFlagSet, setFlag } from './util';
 import 'driver.js/dist/driver.css';
 
 type TourStep = {
   target?: string;
+  showWithoutTarget?: boolean;
   titleKey: string;
   descriptionKey?: string;
   vignette?: Component;
 };
 
 const vaultListTarget = '[data-tour="vaultList"]';
-const adminNavTarget = '[data-tour="adminNav"]';
+
+let activeTour: ReturnType<typeof driver> | undefined;
+
+// driver.js rebuilds the popover per step, so each render unmounts the previous step's content app;
+// module scope lets a replayed tour clean up a predecessor whose onDestroyed hook driver.js skipped
+let contentApp: App | undefined;
+
+function unmountContent() {
+  contentApp?.unmount();
+  contentApp = undefined;
+}
 
 // addVault must be gated explicitly because the button is always rendered, merely disabled;
 // the admin step needs no role check: its target only exists for admins and invisible steps are skipped
 /** exported for testing */
 export function tourSteps(canCreateVaults: boolean): TourStep[] {
   return [
     { titleKey: 'onboarding.welcome.title', descriptionKey: 'onboarding.welcome.description', vignette: WelcomeVignette },
-    { target: vaultListTarget, titleKey: 'onboarding.vaultList.title', descriptionKey: canCreateVaults ? 'onboarding.vaultList.description' : 'onboarding.vaultList.description.shared', vignette: VaultListVignette },
+    { target: vaultListTarget, titleKey: 'onboarding.vaultList.title', descriptionKey: canCreateVaults ? 'onboarding.vaultList.owner.description' : 'onboarding.vaultList.member.description', vignette: VaultListVignette },
     canCreateVaults
       ? { target: '[data-tour="addVault"]', titleKey: 'onboarding.addVault.title', descriptionKey: 'onboarding.addVault.description' }
-      : { target: vaultListTarget, titleKey: 'onboarding.useVault.title', descriptionKey: 'onboarding.useVault.description' },
-    { target: adminNavTarget, titleKey: 'onboarding.adminNav.title', descriptionKey: 'onboarding.adminNav.description' },
-    { target: '[data-tour="profile"]', titleKey: 'onboarding.profile.title', descriptionKey: 'onboarding.profile.description', vignette: ProfileVignette },
+      : { titleKey: 'onboarding.useVault.title', descriptionKey: 'onboarding.useVault.description' },
+    { target: '[data-tour="adminNav"]', titleKey: 'onboarding.adminNav.title', descriptionKey: 'onboarding.adminNav.description' },
+    // the account step must reach everyone, so it falls back to a floating card when the sidebar is hidden
+    { target: '[data-tour="profile"]', showWithoutTarget: true, titleKey: 'onboarding.profile.title', descriptionKey: 'onboarding.profile.description', vignette: ProfileVignette },
     { titleKey: 'onboarding.getApp.title', vignette: GetAppStep }
   ];
 }
@@ -40,27 +53,26 @@ function onboardingKey(userId: string): string {
   return `hub.onboardingCompleted.${userId}`;
 }
 
-function isOnboardingCompleted(userId: string): boolean {
-  try {
-    return localStorage.getItem(onboardingKey(userId)) !== null;
-  } catch {
-    // without localStorage we cannot remember a completion, so rather skip the tour than repeat it on every visit
-    return true;
-  }
+// bumped on completion, so long-lived components like the sidebar react without a reload
+const completionVersion = ref(0);
+
+/** also gates UI that should only appear once the tour is over, e.g. the sidebar app hint */
+export function isOnboardingCompleted(userId: string): boolean {
+  void completionVersion.value; // subscribes reactive callers to tour completions
+  return isFlagSet(onboardingKey(userId));
 }
 
-function setOnboardingCompleted(userId: string) {
-  try {
-    localStorage.setItem(onboardingKey(userId), new Date().toISOString());
-  } catch {
-    // if localStorage is unavailable, the tour may show again next time
-  }
+function completeOnboarding(userId: string) {
+  setFlag(onboardingKey(userId));
+  completionVersion.value++;
 }
 
 function findVisibleElement(selector: string): Element | undefined {
-  return Array.from(document.querySelectorAll(selector)).find(element => element.checkVisibility());
+  return Array.from(document.querySelectorAll(selector)).find(element => element.checkVisibility() && !element.matches(':disabled'));
 }
 
+// driver.js' own waitForElement cannot be used here: the steps are filtered and their duplicate
+// anchors resolved to the visible instance before the tour is built
 async function waitForVisibleElement(selector: string): Promise<boolean> {
   for (let attempt = 0; attempt < 80 && !findVisibleElement(selector); attempt++) {
     await new Promise(resolve => setTimeout(resolve, 50));
@@ -85,7 +97,7 @@ export async function startOnboardingIfNeeded(userId: string) {
  * @param userId the id of the currently logged in user
  */
 export async function startOnboarding(userId: string) {
-  await driveTour(tourSteps((await auth).hasRole('create-vaults')), () => setOnboardingCompleted(userId));
+  await driveTour(tourSteps((await auth).hasRole('create-vaults')), () => completeOnboarding(userId));
 }
 
 /**
@@ -96,70 +108,66 @@ export function stopOnboarding() {
   const tour = activeTour;
   activeTour = undefined;
   tour?.destroy();
+  // driver.js skips onDestroyed during its highlight transition, so do not rely on it for cleanup
+  unmountContent();
 }
 
-let activeTour: ReturnType<typeof driver> | undefined;
-
-// driver.js rebuilds the popover per step, so each render unmounts the previous step's content app;
-// module scope lets a replayed tour clean up a predecessor whose onDestroyed hook driver.js skipped
-let contentApp: App | undefined;
-
-function unmountContent() {
-  contentApp?.unmount();
-  contentApp = undefined;
-}
-
-async function driveTour(includedSteps: TourStep[], onTourDestroyed?: () => void) {
+async function driveTour(includedSteps: TourStep[], onTourDestroyed: () => void) {
   const { t } = i18n.global;
   if (!await waitForVisibleElement(vaultListTarget)) {
     console.warn('Onboarding tour not started because the vault list did not become visible');
     return;
   }
+  // concurrent starts (e.g. a replay while the auto-start is still waiting) converge on the last caller
   stopOnboarding();
 
   const steps: DriveStep[] = [];
+  const titles: string[] = [];
   const contents: TourPopoverProps[] = [];
   for (const step of includedSteps) {
     const element = step.target ? findVisibleElement(step.target) : undefined;
-    if (step.target && !element) {
+    if (step.target && !element && !step.showWithoutTarget) {
       continue;
     }
-    // the blank placeholder keeps driver.js from hiding the description element it hands to onPopoverRender
-    steps.push({ element, popover: { title: t(step.titleKey), description: ' ' } });
-    contents.push({ content: step.vignette, text: step.descriptionKey ? t(step.descriptionKey) : undefined });
+    // blank placeholders keep driver.js from hiding the title and description elements it hands to onPopoverRender
+    steps.push({ element, popover: { title: ' ', description: ' ' } });
+    titles.push(t(step.titleKey));
+    contents.push({ vignette: step.vignette, text: step.descriptionKey ? t(step.descriptionKey) : undefined });
   }
 
-  activeTour = driver({
+  const tour = driver({
     popoverClass: 'onboarding-popover',
-    overlayColor: 'var(--color-gray-500)',
+    overlayColor: 'var(--color-gray-500, #6b7280)',
     overlayOpacity: 0.75,
     stagePadding: 8,
     stageRadius: 8,
     showProgress: true,
-    // driver.js substitutes {{current}} and {{total}} itself, vue-i18n only places them in the message
-    progressText: t('onboarding.progress', ['{{current}}', '{{total}}']),
-    nextBtnText: t('common.next'),
-    prevBtnText: t('common.previous'),
-    doneBtnText: t('onboarding.done'),
     onPopoverRender: (popover, { state }) => {
-      popover.closeButton.setAttribute('aria-label', t('common.close'));
       unmountContent();
-      const content = state.activeIndex !== undefined ? contents[state.activeIndex] : undefined;
-      if (!content) {
+      const index = state.activeIndex;
+      const content = index !== undefined ? contents[index] : undefined;
+      if (index === undefined || !content) {
         return;
       }
+      // driver.js assigns all of these via innerHTML, so set them as text to keep translations inert
+      popover.title.textContent = titles[index];
+      popover.progress.textContent = t('onboarding.progress', [index + 1, steps.length]);
+      popover.previousButton.textContent = t('common.previous');
+      popover.nextButton.textContent = index === steps.length - 1 ? t('onboarding.done') : t('common.next');
+      popover.closeButton.setAttribute('aria-label', t('common.close'));
       contentApp = createApp(TourPopoverContent, content);
       contentApp.mount(popover.description);
     },
     onDestroyed: () => {
       unmountContent();
       // a tour cancelled via stopOnboarding() has already been detached and must not count as completed
-      if (activeTour !== undefined) {
+      if (activeTour === tour) {
         activeTour = undefined;
-        onTourDestroyed?.();
+        onTourDestroyed();
       }
     },
     steps
   });
-  activeTour.drive();
+  activeTour = tour;
+  tour.drive();
 }

frontend/src/common/onboarding.ts

@@ -176,3 +176,26 @@ class WordEncoder {
 }
 
 export const wordEncoder = new WordEncoder(dictionary);
+
+/**
+ * Checks whether a flag was set via {@link setFlag}.
+ */
+export function isFlagSet(key: string): boolean {
+  try {
+    return localStorage.getItem(key) !== null;
+  } catch {
+    // without localStorage the flag cannot be remembered, so report it as set rather than nag on every visit
+    return true;
+  }
+}
+
+/**
+ * Sets a persistent flag. The stored timestamp is informational; only the key's presence matters.
+ */
+export function setFlag(key: string) {
+  try {
+    localStorage.setItem(key, new Date().toISOString());
+  } catch {
+    // if localStorage is unavailable, the flag may be requested again next time
+  }
+}

frontend/src/common/util.ts

@@ -59,25 +59,27 @@ const adminNav: NavigationItem[] = [
 ];
 
 const profileDropdown: ProfileDropdownItem[][] = [
-  [{ icon: UserIcon, name: 'nav.profile.profile', to: '/app/profile' }],
-  [{ icon: QuestionMarkCircleIcon, name: 'nav.profile.showTour', action: replayTour }],
+  [
+    { icon: UserIcon, name: 'nav.profile.profile', to: '/app/profile' },
+    { icon: QuestionMarkCircleIcon, name: 'nav.profile.showTour', action: replayTour }
+  ],
   [{ icon: ArrowRightStartOnRectangleIcon, name: 'nav.profile.signOut', to: '/app/logout' }]
 ];
 
 const isAdmin = ref(false);
 const licenseStatus = ref<LicenseUserInfoDto>();
 
-let drawerClosed: Deferred<void> | undefined;
+let drawerClosed: Deferred<'closed' | 'reopened'> | undefined;
 
 function onDrawerClosed() {
-  drawerClosed?.resolve();
+  drawerClosed?.resolve('closed');
   drawerClosed = undefined;
 }
 
 // a cancelled leave transition never emits after-leave, which would leave the replay hanging forever
 watch(() => props.mobileOpen, (open) => {
   if (open) {
-    drawerClosed?.reject(new Error('Drawer reopened'));
+    drawerClosed?.resolve('reopened');
     drawerClosed = undefined;
   }
 });
@@ -88,7 +90,9 @@ async function replayTour() {
       // otherwise the tour would highlight the drawer's detaching elements
       drawerClosed ??= new Deferred();
       emit('close');
-      await drawerClosed.promise;
+      if (await drawerClosed.promise === 'reopened') {
+        return;
+      }
     }
     await router.push('/app/vaults');
     await startOnboarding(props.me.id);

frontend/src/components/Sidebar.vue

@@ -20,6 +20,7 @@
         </li>
       </ul>
 
+      <!-- SidebarContent renders twice (drawer and desktop); the tour resolves data-tour anchors to the visible instance -->
       <div v-if="isAdmin" data-tour="adminNav">
         <hr class="border-white/10" />
         <ul role="list" class="mt-3 space-y-1">
@@ -35,7 +36,7 @@
 
     <div v-if="showAppHint" class="relative rounded-lg bg-white/5 p-3 ring-1 ring-white/10">
       <div class="flex items-center gap-x-2.5 pr-6">
-        <img src="/cryptomator.svg" alt="" class="h-7 w-auto shrink-0" />
+        <img src="/app-logo.svg" alt="" class="h-7 w-auto shrink-0" />
         <h3 class="text-sm font-medium text-white">{{ t('appHint.title') }}</h3>
       </div>
       <p class="mt-1.5 text-xs/5 text-gray-400">{{ t('appHint.description') }}</p>
@@ -92,8 +93,10 @@ import { XMarkIcon } from '@heroicons/vue/24/outline';
 import { computed, FunctionalComponent, ref } from 'vue';
 import { useI18n } from 'vue-i18n';
 import { useRoute } from 'vue-router';
-import { appDownloadUrl, dismissAppHint, isAppHintDismissed } from '../common/appdownload';
+import { appDownloadUrl } from '../common/appdownload';
 import { UserDto } from '../common/backend';
+import { isOnboardingCompleted } from '../common/onboarding';
+import { isFlagSet, setFlag } from '../common/util';
 
 export type NavigationItem = { icon: FunctionalComponent, name: string, to: string };
 export type ProfileDropdownItem = { icon: FunctionalComponent, name: string } & ({ to: string } | { action: () => void });
@@ -116,11 +119,14 @@ const emit = defineEmits<{
 }>();
 
 const downloadUrl = appDownloadUrl();
-const appHintDismissed = ref(isAppHintDismissed(props.me.id));
-const showAppHint = computed(() => !appHintDismissed.value && props.me.devices.every(device => device.type === 'BROWSER'));
+const appHintKey = `hub.appHintDismissed.${props.me.id}`;
+const appHintDismissed = ref(isFlagSet(appHintKey));
+// only shown once the tour is over, so it does not compete with the tour's own download step;
+// legacy devices are ignored on purpose: their owners should switch to the current app anyway
+const showAppHint = computed(() => !appHintDismissed.value && isOnboardingCompleted(props.me.id) && props.me.devices.every(device => device.type === 'BROWSER'));
 
 function dismissHint() {
-  dismissAppHint(props.me.id);
+  setFlag(appHintKey);
   appHintDismissed.value = true;
 }
 

frontend/src/components/SidebarContent.vue

@@ -206,7 +206,7 @@ const filteredVaults = computed(() =>
 
 onMounted(async () => {
   await fetchData();
-  if (me.value) {
+  if (me.value && !onFetchError.value) {
     await nextTick();
     await startOnboardingIfNeeded(me.value.id);
   }