sam-react-prod/claudedocs/[IMPL-2025-11-13] sidebar-scroll-improvements.md

사이드바 스크롤 및 UX 개선

개요

레프트 메뉴(사이드바)의 스크롤 기능과 사용자 경험을 개선한 작업입니다. 메뉴가 많아져도 편리하게 탐색할 수 있도록 자동 스크롤, sticky 고정, macOS 스타일 스크롤바 등을 구현했습니다.

작업 일자: 2025-11-13 관련 파일:

• src/components/layout/Sidebar.tsx
• src/layouts/DashboardLayout.tsx
• src/app/globals.css

---

구현된 기능

1. 메뉴 영역 독립 스크롤

문제: 메뉴가 많아도 사이드바가 화면 크기에 맞춰 늘어나서 스크롤이 생기지 않음

해결:

• 사이드바 컨테이너에 고정 높이 설정: h-[calc(100vh-24px)]
• 메뉴 영역에 flex-1 overflow-y-auto 적용
• 화면 전체 스크롤과 독립적으로 메뉴만 스크롤 가능

파일: src/layouts/DashboardLayout.tsx:166

<div
  className={`h-[calc(100vh-24px)] border-none bg-transparent hidden md:block ...`}
>

파일: src/components/layout/Sidebar.tsx:89-93

<div
  ref={menuContainerRef}
  className={`sidebar-scroll flex-1 overflow-y-auto ...`}
>

---

2. 선택된 메뉴 자동 스크롤

문제: 하단 메뉴를 선택하면 활성화되지만 화면에 보이지 않음

해결:

• useRef로 활성 메뉴와 메뉴 컨테이너의 DOM 요소 참조
• useEffect로 activeMenu 변경 감지
• scrollIntoView({ behavior: 'smooth', block: 'nearest' })로 자동 스크롤

파일: src/components/layout/Sidebar.tsx:26-42

// ref 선언
const activeMenuRef = useRef<HTMLDivElement | null>(null);
const menuContainerRef = useRef<HTMLDivElement | null>(null);

// 활성 메뉴 변경 시 자동 스크롤
useEffect(() => {
  if (activeMenuRef.current && menuContainerRef.current) {
    activeMenuRef.current.scrollIntoView({
      behavior: 'smooth',
      block: 'nearest',
      inline: 'nearest',
    });
  }
}, [activeMenu]); // activeMenu 변경 시에만 스크롤

파일: src/components/layout/Sidebar.tsx:105-108, 160-162

// 메인 메뉴에 ref 할당
<div
  key={item.id}
  className="relative"
  ref={isActive ? activeMenuRef : null}
>

// 서브메뉴에 ref 할당
<div
  key={subItem.id}
  ref={isSubActive ? activeMenuRef : null}
>

작동 흐름:

1. 메뉴 클릭 → activeMenu 상태 변경
2. useEffect 실행 (트리거)
3. activeMenuRef.current로 활성 메뉴의 실제 DOM 요소 가져오기
4. scrollIntoView() 메서드로 해당 위치로 스크롤

---

3. 사이드바 Sticky 고정

문제: 컨텐츠가 길어서 스크롤 내리면 사이드바 메뉴가 사라짐

해결:

• 사이드바 컨테이너에 sticky top-3 적용
• 페이지 스크롤 시에도 사이드바가 항상 화면에 고정됨
• top-3은 페이지 패딩(p-3)과 일치하여 자연스러운 위치 유지

파일: src/layouts/DashboardLayout.tsx:166

<div
  className={`sticky top-3 h-[calc(100vh-24px)] ...`}
>

동작:

• 페이지 스크롤 시 사이드바가 상단(12px 떨어진 위치)에 고정
• 메뉴 내부는 독립적으로 스크롤 가능
• 컨텐츠가 짧을 때는 일반적으로 표시

---

4. 불필요한 스크롤 방지

문제: 서브메뉴를 확장/축소할 때마다 스크롤이 이동함

해결:

• useEffect 의존성 배열에서 expandedMenus 제거
• activeMenu 변경 시에만 스크롤 실행
• 서브메뉴 토글은 스크롤 없이 제자리에서 확장/축소

파일: src/components/layout/Sidebar.tsx:42

// 변경 전
}, [activeMenu, expandedMenus]); // expandedMenus 때문에 불필요한 스크롤

// 변경 후
}, [activeMenu]); // activeMenu 변경 시에만 스크롤

시나리오:

1. "회계관리" 서브메뉴 확장 → ❌ 스크롤 안 함 (현재 위치 유지)
2. "기준정보 관리" 클릭 → ✅ "기준정보 관리"로 스크롤
3. "회계관리 > 계정과목" 클릭 → ✅ "계정과목"으로 스크롤

---

5. URL 직접 접근 시 하위 메뉴 자동 확장

문제: URL로 서브메뉴에 직접 접근하면 부모 메뉴가 접혀있어서 활성 메뉴가 보이지 않음

해결:

• 경로 매칭 순서 변경: 서브메뉴를 먼저 확인
• 더 구체적인 경로(긴 경로)를 우선 매칭
• 서브메뉴 매칭 시 부모 메뉴 자동 확장

파일: src/layouts/DashboardLayout.tsx:90-107

const findActiveMenu = (items: MenuItem[]): { menuId: string; parentId?: string } | null => {
  for (const item of items) {
    // 1. 서브메뉴를 먼저 확인 (더 구체적인 경로 우선)
    if (item.children && item.children.length > 0) {
      for (const child of item.children) {
        if (child.path && normalizedPath.startsWith(child.path)) {
          return { menuId: child.id, parentId: item.id };
        }
      }
    }

    // 2. 서브메뉴에서 매칭되지 않으면 현재 메뉴 확인
    if (item.path && normalizedPath.startsWith(item.path)) {
      return { menuId: item.id };
    }
  }
  return null;
};

예시:

• URL: /base/account-subject
• 부모 경로: /base
• 자식 경로: /base/account-subject

변경 전 (문제):

1. /base/account-subject.startsWith(/base) → true
2. 부모 메뉴 "회계관리"만 활성화
3. 서브메뉴 확인 코드에 도달하지 못함

변경 후 (해결):

1. 먼저 서브메뉴 확인: /base/account-subject.startsWith(/base/account-subject) → true
2. 서브메뉴 "계정과목" 활성화 + 부모 "회계관리" 자동 확장
3. "계정과목"으로 자동 스크롤

---

6. macOS 스타일 스크롤바

문제: 스크롤바가 항상 보여서 UI가 복잡해 보임

해결:

• 평소에는 스크롤바 숨김 (투명)
• 메뉴 영역에 hover 시에만 스크롤바 표시
• 얇고 미니멀한 디자인 (6px)
• 부드러운 fade-in/out 애니메이션

파일: src/app/globals.css:301-344

/* Sidebar scroll - hide by default, show on hover */
.sidebar-scroll::-webkit-scrollbar {
  width: 6px;
}

.sidebar-scroll::-webkit-scrollbar-track {
  background: transparent;
}

.sidebar-scroll::-webkit-scrollbar-thumb {
  background: transparent;  /* 기본 투명 */
  border-radius: 3px;
  transition: background 0.2s ease;
}

.sidebar-scroll:hover::-webkit-scrollbar-thumb {
  background: rgba(0, 0, 0, 0.15);  /* hover 시 나타남 */
}

.dark .sidebar-scroll:hover::-webkit-scrollbar-thumb {
  background: rgba(255, 255, 255, 0.15);  /* 다크모드 */
}

.sidebar-scroll::-webkit-scrollbar-thumb:hover {
  background: rgba(0, 0, 0, 0.25) !important;  /* 스크롤바 자체 hover */
}

/* Firefox 지원 */
.sidebar-scroll {
  scrollbar-width: thin;
  scrollbar-color: transparent transparent;
}

.sidebar-scroll:hover {
  scrollbar-color: rgba(0, 0, 0, 0.15) transparent;
}

파일: src/components/layout/Sidebar.tsx:91

<div className="sidebar-scroll flex-1 overflow-y-auto ...">

동작:

• 평소: 스크롤바 투명 (보이지 않지만 스크롤 가능)
• 메뉴 영역 hover: 스크롤바가 부드럽게 나타남
• 스크롤바 hover: 더 진하게 표시 (명확한 인터랙션)
• 다크모드 & 시니어모드: 테마별 색상 자동 적용

지원 브라우저:

• Chrome, Safari, Edge (Webkit)
• Firefox (scrollbar-color)

---

기술적 이해

ref와 DOM 조작

// 역할 분담
const activeMenuRef = useRef<HTMLDivElement | null>(null);  // DOM 참조 수단

useEffect(() => {
  // ref를 통해 실제 DOM 요소 가져오기
  const element = activeMenuRef.current;

  // DOM 메서드 호출 (명령형 조작)
  element.scrollIntoView({ behavior: 'smooth' });

}, [activeMenu]);  // 트리거 조건

구분	역할	코드
트리거	언제 실행할지	[activeMenu] 의존성 배열
ref	어떤 DOM 요소를	activeMenuRef.current
조작	무엇을 할지	scrollIntoView() 메서드

흐름:

1. 메뉴 클릭 → activeMenu 상태 변경 (React 상태)
2. useEffect 실행 (트리거 조건 충족)
3. activeMenuRef.current로 실제 DOM 요소 참조
4. scrollIntoView() 메서드로 스크롤 조작 (명령형)

비유:

"불이 켜지면(activeMenu 변경), 저 스위치를(activeMenuRef), 눌러라(scrollIntoView)"

CSS 우선순위와 특수성

/* 기본 스크롤바 (전역) */
::-webkit-scrollbar-thumb {
  background: rgba(0, 0, 0, 0.2);
}

/* 사이드바 스크롤바 (특정 클래스) */
.sidebar-scroll::-webkit-scrollbar-thumb {
  background: transparent;  /* 더 높은 특수성으로 오버라이드 */
}

/* hover 상태 */
.sidebar-scroll:hover::-webkit-scrollbar-thumb {
  background: rgba(0, 0, 0, 0.15);  /* 더욱 높은 특수성 */
}

---

사용자 경험 개선 효과

Before (개선 전)

• ❌ 메뉴가 많으면 사이드바가 계속 늘어남
• ❌ 하단 메뉴 선택 시 화면에 보이지 않음
• ❌ 스크롤 내리면 메뉴가 사라짐
• ❌ 서브메뉴 토글 시 화면이 튀어다님
• ❌ URL 접근 시 서브메뉴가 접혀있음
• ❌ 스크롤바가 항상 보여서 복잡함

After (개선 후)

• ✅ 메뉴 영역에 독립적인 스크롤
• ✅ 선택한 메뉴가 자동으로 화면에 보임
• ✅ 스크롤해도 메뉴가 항상 보임 (sticky)
• ✅ 메뉴 클릭 시에만 스크롤 이동
• ✅ URL 접근 시 자동으로 경로 확장
• ✅ 필요할 때만 스크롤바 표시

---

테스트 시나리오

1. 메뉴 스크롤 테스트

1. 메뉴가 20개 이상 있는 상태
2. 최하단 메뉴 클릭
3. 기대 결과: 해당 메뉴가 화면에 보이도록 자동 스크롤

2. Sticky 테스트

1. 컨텐츠가 긴 페이지 접속
2. 페이지를 아래로 스크롤
3. 기대 결과: 사이드바가 상단에 고정되어 계속 보임

3. 서브메뉴 테스트

1. "회계관리" 서브메뉴 확장
2. 다른 메뉴 클릭 (예: "기준정보 관리")
3. 기대 결과: "기준정보 관리"로만 스크롤, "회계관리"는 스크롤 안 함

4. URL 직접 접근 테스트

1. 브라우저 주소창에 /base/account-subject 입력
2. 기대 결과:
   • "회계관리" 서브메뉴 자동 확장
   • "계정과목" 활성화 및 화면에 표시

5. 스크롤바 표시 테스트

1. 메뉴 영역에 마우스를 올리지 않은 상태
2. 기대 결과: 스크롤바 보이지 않음
3. 메뉴 영역에 마우스 hover
4. 기대 결과: 스크롤바가 부드럽게 나타남

---

브라우저 호환성

기능	Chrome	Safari	Firefox	Edge
메뉴 스크롤	✅	✅	✅	✅
Sticky 고정	✅	✅	✅	✅
자동 스크롤	✅	✅	✅	✅
커스텀 스크롤바	✅ (Webkit)	✅ (Webkit)	✅ (scrollbar-color)	✅ (Webkit)

---

향후 개선 가능 사항

1. 스크롤 위치 기억: 페이지 새로고침 시 이전 스크롤 위치 복원
2. 키보드 네비게이션: 화살표 키로 메뉴 탐색 + 자동 스크롤
3. 접근성 개선: ARIA 레이블 및 스크린 리더 지원
4. 애니메이션 최적화: will-change 속성으로 성능 개선
5. 모바일 제스처: 스와이프로 메뉴 열기/닫기

---

관련 문서

• React useRef 공식 문서
• scrollIntoView() MDN
• CSS position: sticky MDN
• CSS Scrollbar Styling MDN

---

작성자 노트

이번 개선 작업은 단순히 기능 추가가 아닌, 사용자 경험의 전반적인 개선에 초점을 맞췄습니다. 특히:

1. 직관성: 메뉴를 클릭하면 자동으로 보이는 것이 당연함
2. 일관성: 클릭이든 URL이든 동일한 방식으로 동작
3. 미니멀리즘: 필요할 때만 UI 요소 표시 (스크롤바)
4. 성능: 불필요한 리렌더링과 스크롤 방지

이러한 작은 개선들이 모여 전체적인 사용자 만족도를 크게 향상시킬 수 있습니다.