From 258b2622d5508f3b00a0c6ba15bece59008bc239 Mon Sep 17 00:00:00 2001
From: Will Miao <willmiao.dev@gmail.com>
Date: Thu, 18 Jun 2026 19:22:38 +0800
Subject: [PATCH] fix(sidebar): align restore indicator with sidebar header and
 add first-use breathing animation (#990)

---
 static/css/components/sidebar.css      | 18 ++++++++++++++++--
 static/js/components/SidebarManager.js |  8 ++++++++
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/static/css/components/sidebar.css b/static/css/components/sidebar.css
index a52e878e..7eaa75d6 100644
--- a/static/css/components/sidebar.css
+++ b/static/css/components/sidebar.css
@@ -114,8 +114,7 @@
 .sidebar-hidden-indicator {
     position: fixed;
     left: 0;
-    top: 50%;
-    transform: translateY(-50%);
+    top: 68px; /* Align with sidebar header */
     z-index: var(--z-overlay);
     width: 14px;
     height: 44px;
@@ -144,6 +143,21 @@
     color: white;
 }
 
+/* Subtle breathing animation for first-time discovery */
+@keyframes sidebarBreathing {
+    0%, 100% { opacity: 0.3; }
+    50%      { opacity: 0.65; }
+}
+
+.sidebar-hidden-indicator.breathing {
+    animation: sidebarBreathing 2.5s ease-in-out infinite;
+    animation-delay: 0.5s;
+}
+
+.sidebar-hidden-indicator.breathing:hover {
+    animation: none;
+}
+
 .sidebar-hidden-indicator-tooltip {
     position: absolute;
     left: 100%;
diff --git a/static/js/components/SidebarManager.js b/static/js/components/SidebarManager.js
index 3f83004b..afba1f8a 100644
--- a/static/js/components/SidebarManager.js
+++ b/static/js/components/SidebarManager.js
@@ -1040,7 +1040,15 @@ export class SidebarManager {
             <span class="sidebar-hidden-indicator-tooltip">${translate('sidebar.showSidebar')}</span>
         `;
 
+        // Subtle breathing animation on first sight to aid discoverability;
+        // stops permanently after user clicks the restore button once
+        const restoreKey = `${this.pageType}_restoreButtonUsed`;
+        if (!getStorageItem(restoreKey, false)) {
+            indicator.classList.add('breathing');
+        }
+
         indicator.addEventListener('click', () => {
+            setStorageItem(restoreKey, true);
             this.toggleHideOnThisPage();
         });