sam-react-prod/docs/[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`
```tsx
<div
  className={`h-[calc(100vh-24px)] border-none bg-transparent hidden md:block ...`}
>
```

**파일**: `src/components/layout/Sidebar.tsx:89-93`
```tsx
<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`
```tsx
// 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`
```tsx
// 메인 메뉴에 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`
```tsx
<div
  className={`sticky top-3 h-[calc(100vh-24px)] ...`}
>
```

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

---

### 4. 불필요한 스크롤 방지

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

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

**파일**: `src/components/layout/Sidebar.tsx:42`
```tsx
// 변경 전
}, [activeMenu, expandedMenus]); // expandedMenus 때문에 불필요한 스크롤

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

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

---

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

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

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

**파일**: `src/layouts/DashboardLayout.tsx:90-107`
```tsx
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`
```css
/* 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`
```tsx
<div className="sidebar-scroll flex-1 overflow-y-auto ...">
```

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

**지원 브라우저**:
- Chrome, Safari, Edge (Webkit)
- Firefox (scrollbar-color)

---

## 기술적 이해

### ref와 DOM 조작

```tsx
// 역할 분담
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 우선순위와 특수성

```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 공식 문서](https://react.dev/reference/react/useRef)
- [scrollIntoView() MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView)
- [CSS position: sticky MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/position#sticky)
- [CSS Scrollbar Styling MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/::-webkit-scrollbar)

---

## 작성자 노트

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

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

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