From 1603796856962f9782be1a572a9fbe06ce970050 Mon Sep 17 00:00:00 2001
From: Truman Gao <106889354+tdgao@users.noreply.github.com>
Date: Wed, 15 Apr 2026 10:53:08 -0600
Subject: [PATCH] feat: implement overlay scrollbar for app sidebar (#5820)

* feat: implement overlay scrollbar for app sidebar

* pnpm prepr
---
 apps/app-frontend/package.json                |  1 +
 apps/app-frontend/src/App.vue                 | 31 ++++++++++------
 .../src/components/ui/friends/FriendsList.vue | 10 +++---
 .../components/ui/friends/FriendsSection.vue  |  4 +--
 .../src/directives/overlayScrollbars.ts       | 35 +++++++++++++++++++
 apps/app-frontend/src/main.js                 |  3 ++
 packages/assets/generated-icons.ts            |  4 +--
 pnpm-lock.yaml                                |  8 +++++
 8 files changed, 77 insertions(+), 19 deletions(-)
 create mode 100644 apps/app-frontend/src/directives/overlayScrollbars.ts

diff --git a/apps/app-frontend/package.json b/apps/app-frontend/package.json
index e32e82564..48037e284 100644
--- a/apps/app-frontend/package.json
+++ b/apps/app-frontend/package.json
@@ -35,6 +35,7 @@
 		"fuse.js": "^6.6.2",
 		"intl-messageformat": "^10.7.7",
 		"ofetch": "^1.3.4",
+		"overlayscrollbars": "^2.15.1",
 		"pinia": "^3.0.0",
 		"posthog-js": "^1.158.2",
 		"three": "^0.172.0",
diff --git a/apps/app-frontend/src/App.vue b/apps/app-frontend/src/App.vue
index 97344d945..d8148524d 100644
--- a/apps/app-frontend/src/App.vue
+++ b/apps/app-frontend/src/App.vue
@@ -428,6 +428,13 @@ loading.startLoading()
 
 let suspensePending = false
 
+const sidebarOverlayScrollbarsOptions = Object.freeze({
+	overflow: {
+		x: 'hidden',
+		y: 'scroll',
+	},
+})
+
 router.beforeEach(() => {
 	suspensePending = false
 	loading.startLoading()
@@ -1279,29 +1286,26 @@ provideAppUpdateDownloadProgress(appUpdateDownload)
 			</RouterView>
 		</div>
 		<div
-			class="app-sidebar mt-px shrink-0 flex flex-col border-0 border-l-[1px] border-[--brand-gradient-border] border-solid overflow-auto"
+			v-overlay-scrollbars="sidebarOverlayScrollbarsOptions"
+			class="app-sidebar mt-px shrink-0 flex flex-col border-0 border-l-[1px] border-[--brand-gradient-border] border-solid"
 			:class="{ 'has-plus': hasPlus }"
+			data-overlayscrollbars-initialize
 		>
-			<div
-				class="app-sidebar-scrollable flex-grow shrink overflow-y-auto relative"
-				:class="{ 'pb-12': !hasPlus }"
-			>
+			<div class="app-sidebar-scrollable flex-grow shrink relative" :class="{ 'pb-12': !hasPlus }">
 				<div id="sidebar-teleport-target" class="sidebar-teleport-content"></div>
 				<div class="sidebar-default-content" :class="{ 'sidebar-enabled': sidebarVisible }">
-					<div
-						class="p-4 pr-1 border-0 border-b-[1px] border-[--brand-gradient-border] border-solid"
-					>
+					<div class="p-4 border-0 border-b-[1px] border-[--brand-gradient-border] border-solid">
 						<h3 class="text-base text-primary font-medium m-0">Playing as</h3>
 						<suspense>
 							<AccountsCard ref="accounts" mode="small" />
 						</suspense>
 					</div>
-					<div class="py-4 border-0 border-b-[1px] border-[--brand-gradient-border] border-solid">
+					<div class="p-4 border-0 border-b-[1px] border-[--brand-gradient-border] border-solid">
 						<suspense>
 							<FriendsList :credentials="credentials" :sign-in="() => signIn()" />
 						</suspense>
 					</div>
-					<div v-if="news && news.length > 0" class="p-4 pr-1 flex flex-col items-center">
+					<div v-if="news && news.length > 0" class="p-4 flex flex-col items-center">
 						<h3 class="text-base mb-4 text-primary font-medium m-0 text-left w-full">News</h3>
 						<div class="space-y-4 flex flex-col items-center w-full">
 							<NewsArticleCard
@@ -1649,6 +1653,13 @@ provideAppUpdateDownloadProgress(appUpdateDownload)
 }
 </style>
 <style>
+.os-theme-dark,
+.os-theme-light {
+	--os-handle-bg: var(--color-scrollbar) !important;
+	--os-handle-bg-hover: var(--color-scrollbar) !important;
+	--os-handle-bg-active: var(--color-scrollbar) !important;
+}
+
 .mac {
 	.app-grid-statusbar {
 		padding-left: 5rem;
diff --git a/apps/app-frontend/src/components/ui/friends/FriendsList.vue b/apps/app-frontend/src/components/ui/friends/FriendsList.vue
index 8120e050d..ba9e78d69 100644
--- a/apps/app-frontend/src/components/ui/friends/FriendsList.vue
+++ b/apps/app-frontend/src/components/ui/friends/FriendsList.vue
@@ -288,7 +288,7 @@ const messages = defineMessages({
 			</div>
 		</div>
 	</ModalWrapper>
-	<div v-if="userCredentials && !loading" class="flex gap-1 items-center mb-3 ml-2 mr-1">
+	<div v-if="userCredentials && !loading" class="flex gap-1 items-center mb-3 -ml-1">
 		<template v-if="sortedFriends.length > 0">
 			<ButtonStyled circular type="transparent">
 				<button
@@ -309,7 +309,7 @@ const messages = defineMessages({
 				@keyup.esc="search = ''"
 			/>
 		</template>
-		<h3 v-else class="ml-2 w-full text-base text-primary font-medium m-0">
+		<h3 v-else class="w-full text-base text-primary font-medium m-0">
 			{{ formatMessage(messages.friends) }}
 		</h3>
 		<ButtonStyled v-if="incomingRequests.length > 0" circular type="transparent">
@@ -331,11 +331,11 @@ const messages = defineMessages({
 		</ButtonStyled>
 	</div>
 	<div class="flex flex-col gap-3">
-		<h3 v-if="loading" class="ml-4 mr-1 text-base text-primary font-medium m-0">
+		<h3 v-if="loading" class="text-base text-primary font-medium m-0">
 			{{ formatMessage(messages.friends) }}
 		</h3>
 		<template v-if="loading">
-			<div v-for="n in 5" :key="n" class="flex gap-2 items-center animate-pulse ml-4 mr-1">
+			<div v-for="n in 5" :key="n" class="flex gap-2 items-center animate-pulse">
 				<div class="min-w-9 min-h-9 bg-button-bg rounded-full"></div>
 				<div class="flex flex-col w-full">
 					<div class="h-3 bg-button-bg rounded-full w-1/2 mb-1"></div>
@@ -344,7 +344,7 @@ const messages = defineMessages({
 			</div>
 		</template>
 		<template v-else-if="sortedFriends.length === 0">
-			<div class="text-sm ml-4 mr-1">
+			<div class="text-sm">
 				<div v-if="!userCredentials">
 					<IntlFormatted :message-id="messages.signInToAddFriends">
 						<template #link="{ children }">
diff --git a/apps/app-frontend/src/components/ui/friends/FriendsSection.vue b/apps/app-frontend/src/components/ui/friends/FriendsSection.vue
index 0f30b311e..3868c387d 100644
--- a/apps/app-frontend/src/components/ui/friends/FriendsSection.vue
+++ b/apps/app-frontend/src/components/ui/friends/FriendsSection.vue
@@ -106,7 +106,7 @@ const messages = defineMessages({
 		:open-by-default="openByDefault"
 		:force-open="isSearching"
 		:button-class="
-			'pl-4 pr-3 flex w-full items-center bg-transparent border-0 p-0' +
+			'flex w-full items-center bg-transparent border-0 p-0' +
 			(isSearching
 				? ''
 				: ' cursor-pointer hover:brightness-[--hover-brightness] active:scale-[0.98] transition-all')
@@ -122,7 +122,7 @@ const messages = defineMessages({
 				<div
 					v-for="friend in friends"
 					:key="friend.username"
-					class="group grid items-center grid-cols-[auto_1fr_auto] gap-2 hover:bg-button-bg transition-colors rounded-full ml-4 mr-1"
+					class="group grid items-center grid-cols-[auto_1fr_auto] gap-2 hover:bg-button-bg transition-colors rounded-full mr-1"
 					@contextmenu.prevent.stop="
 						(event) => friendOptions?.showMenu(event, friend, createContextMenuOptions(friend))
 					"
diff --git a/apps/app-frontend/src/directives/overlayScrollbars.ts b/apps/app-frontend/src/directives/overlayScrollbars.ts
new file mode 100644
index 000000000..a58b33e9c
--- /dev/null
+++ b/apps/app-frontend/src/directives/overlayScrollbars.ts
@@ -0,0 +1,35 @@
+import { OverlayScrollbars, type PartialOptions } from 'overlayscrollbars'
+import type { ObjectDirective } from 'vue'
+
+const defaultOverlayScrollbarsOptions = Object.freeze<PartialOptions>({
+	scrollbars: {
+		theme: 'os-theme-dark',
+		autoHide: 'leave',
+		autoHideSuspend: true,
+	},
+})
+
+const mergeOptions = (options: PartialOptions = {}): PartialOptions => ({
+	...defaultOverlayScrollbarsOptions,
+	...options,
+	scrollbars: {
+		...defaultOverlayScrollbarsOptions.scrollbars,
+		...(options.scrollbars ?? {}),
+	},
+})
+
+export const overlayScrollbarsDirective: ObjectDirective<HTMLElement, PartialOptions | undefined> =
+	{
+		mounted(el, binding) {
+			OverlayScrollbars(el, mergeOptions(binding.value))
+		},
+		updated(el, binding) {
+			if (binding.value === binding.oldValue) return
+			const instance = OverlayScrollbars(el)
+			instance?.options(mergeOptions(binding.value))
+		},
+		unmounted(el) {
+			const instance = OverlayScrollbars(el)
+			instance?.destroy()
+		},
+	}
diff --git a/apps/app-frontend/src/main.js b/apps/app-frontend/src/main.js
index b9da36b0d..c9dfd2b34 100644
--- a/apps/app-frontend/src/main.js
+++ b/apps/app-frontend/src/main.js
@@ -1,4 +1,5 @@
 import 'floating-vue/dist/style.css'
+import 'overlayscrollbars/overlayscrollbars.css'
 
 import * as Sentry from '@sentry/vue'
 import { VueScanPlugin } from '@taijased/vue-render-tracker'
@@ -8,6 +9,7 @@ import { createPinia } from 'pinia'
 import { createApp } from 'vue'
 
 import App from '@/App.vue'
+import { overlayScrollbarsDirective } from '@/directives/overlayScrollbars'
 import i18nPlugin from '@/plugins/i18n'
 import i18nDebugPlugin from '@/plugins/i18n-debug'
 import router from '@/routes'
@@ -50,5 +52,6 @@ app.use(FloatingVue, {
 })
 app.use(i18nPlugin)
 app.use(i18nDebugPlugin)
+app.directive('overlay-scrollbars', overlayScrollbarsDirective)
 
 app.mount('#app')
diff --git a/packages/assets/generated-icons.ts b/packages/assets/generated-icons.ts
index 7e815d793..03015155f 100644
--- a/packages/assets/generated-icons.ts
+++ b/packages/assets/generated-icons.ts
@@ -3,6 +3,8 @@
 
 import type { FunctionalComponent, SVGAttributes } from 'vue'
 
+export type IconComponent = FunctionalComponent<SVGAttributes>
+
 import _AffiliateIcon from './icons/affiliate.svg?component'
 import _AlignLeftIcon from './icons/align-left.svg?component'
 import _ArchiveIcon from './icons/archive.svg?component'
@@ -392,8 +394,6 @@ import _XCircleIcon from './icons/x-circle.svg?component'
 import _ZoomInIcon from './icons/zoom-in.svg?component'
 import _ZoomOutIcon from './icons/zoom-out.svg?component'
 
-export type IconComponent = FunctionalComponent<SVGAttributes>
-
 export const AffiliateIcon = _AffiliateIcon
 export const AlignLeftIcon = _AlignLeftIcon
 export const ArchiveIcon = _ArchiveIcon
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 24919b46d..540560cec 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -137,6 +137,9 @@ importers:
       ofetch:
         specifier: ^1.3.4
         version: 1.5.1
+      overlayscrollbars:
+        specifier: ^2.15.1
+        version: 2.15.1
       pinia:
         specifier: ^3.0.0
         version: 3.0.4(typescript@5.9.3)(vue@3.5.27(typescript@5.9.3))
@@ -7604,6 +7607,9 @@ packages:
     resolution: {integrity: sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==}
     engines: {node: '>= 0.8.0'}
 
+  overlayscrollbars@2.15.1:
+    resolution: {integrity: sha512-glX26JwjL+Tkzv0JNOWdW4VozP5dGXO+Wx8+TPrdTEJTSYT/8eJS8yXM+fewjU0nFq/JeCa+X+BqABNjC4YZSA==}
+
   oxc-minify@0.110.0:
     resolution: {integrity: sha512-KWGTzPo83QmGrXC4ml83PM9HDwUPtZFfasiclUvTV4i3/0j7xRRqINVkrL77CbQnoWura3CMxkRofjQKVDuhBw==}
     engines: {node: ^20.19.0 || >=22.12.0}
@@ -17717,6 +17723,8 @@ snapshots:
       type-check: 0.4.0
       word-wrap: 1.2.5
 
+  overlayscrollbars@2.15.1: {}
+
   oxc-minify@0.110.0:
     optionalDependencies:
       '@oxc-minify/binding-android-arm-eabi': 0.110.0