[FIX] 모달 스택 z-index가 닫을 때 반납되지 않는 문제

[jjangminii]

ISSUE 🔗

close #320

What is this PR? 🔍

모달 스택 깊이를 세는 카운터가 모달이 닫혀도 반납되지 않던 문제를 고쳤습니다. Modal과 OverlayModal 양쪽에 반납 로직을 추가하고, 중복 open 호출에 대한 가드도 더했습니다.

배경

• 기존 구조: Modal·OverlayModal이 모달을 열 때마다 acquireModalStackIndex()로 번호를 받아 z-index(BASE + index * STEP)를 계산했는데, 이 번호를 닫을 때 반납하는 코드가 없었습니다.
• 발생 문제: nextModalStackIndex가 세션 내내 증가만 해서, 전혀 중첩되지 않은 단일 모달도 모달을 여러 번 열었다 닫았다 하면 점점 더 큰 z-index를 받았습니다. 공용 AnimatedToast처럼 z-50 고정값을 쓰는 다른 요소가 "모달은 대략 50 근처"라고 가정하고 있어서, 세션이 길어지면 그 가정이 깨질 수 있었습니다.
• 해결 방향: acquire와 짝이 되는 release를 추가해서, 카운터가 "세션 누적 오픈 횟수"가 아니라 "지금 동시에 열려 있는 개수"를 반영하도록 했습니다.

modal-stack-registry / Modal

• 변경 요약: releaseModalStackIndex를 추가하고, Modal이 닫히거나(버튼, Escape, 바깥 클릭 등 어떤 경로든) 언마운트될 때 호출하도록 했습니다. open()이 이미 열린 상태에서 중복 호출돼도 다시 acquire하지 않도록 가드도 추가했습니다.
• 이유: open()이 가드 없이 매번 acquire하는데, 이미 열린 상태에서 또 호출되면(같은 값으로 setIsOpen(true)를 또 부르는 경우) React가 리렌더를 건너뛰어서 release를 맡은 effect가 다시 등록되지 않습니다. 그러면 모달이 완전히 닫혀도 카운트가 남습니다.
• 구현 방식: useEffect(() => { if (!isOpen) return; return () => releaseModalStackIndex(); }, [isOpen])로 acquire와 release를 짝지었습니다. React StrictMode의 effect 이중 실행은 "새로 마운트되는 커밋"에만 적용되는데, 이 컴포넌트는 항상 isOpen=false로 마운트된 뒤 나중에 열리므로 이중 실행과 겹치지 않는다는 걸 React 소스(recursivelyTraverseAndDoubleInvokeEffectsInDEV, Placement 플래그 기준 분기)로 확인했습니다.

OverlayModal

• 변경 요약: 같은 방식으로 release를 추가했습니다.
• 이유: OverlayModal은 닫힌 뒤에도 200ms 퇴장 애니메이션(shouldRender)이 끝날 때까지 화면에 남아 있습니다.
• 구현 방식: isOpen이 아니라 shouldRender에 맞춰 반납합니다. isOpen 기준으로 하면 페이드아웃 중인 모달이 아직 쓰고 있는 z-index를 그사이 새로 열리는 모달이 받아갈 수 있어서, 애니메이션이 완전히 끝나는 시점에 반납하도록 했습니다.
• 경계 · 제약: Modal처럼 open()류의 중복 호출 가드는 이 컴포넌트엔 해당 사항이 없습니다(isOpen을 부모가 prop으로 제어하는 구조라, 값이 안 바뀌면 애초에 effect가 다시 안 돕니다).

To Reviewers

• 카운터 증감 로직(중첩/비중첩 open-close 순서)은 레지스트리 함수만 따로 떼어 시나리오별로 직접 실행해 확인했습니다.
• React StrictMode 이중 실행과 얽히는지도 검토했고, 이 사용 패턴(항상 닫힌 채로 마운트)에서는 문제되지 않는다는 근거를 본문에 적었습니다. 혹시 모달을 처음부터 열린 상태로 마운트하는 화면이 있다면(지금은 없는 것으로 확인했습니다) 이 전제가 깨질 수 있어서 짚어주시면 좋겠습니다.

Screenshot 📷

Test Checklist ✔

• pnpm check-types(apps/timo-web, packages/timo-design-system) 통과
• pnpm lint(ESLint, 변경 범위) 통과
• pnpm prettier --check(변경 범위) 통과
• 레지스트리 카운터 증감 로직을 별도 스크립트로 시나리오 테스트(중첩/비중첩 open-close)
• 브라우저에서 실제 중첩 모달 동작 확인 — 미실행

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
timo-client-timo-web	Ready	Preview	Oct 10, 2026 2:41pm UTC

[coderabbitai]

Warning

Review limit reached

This review ran on the open-source allowance, not this organization's plan, because the pull request author doesn't have an assigned seat. Waiting won't change this — ask an organization admin to assign them a seat, or add seats in Billing if every seat is already assigned, then retry.

Next included review available in 53 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Repository: Team-Timo/Timo-client/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 0c8765b0-255d-4747-94ef-77d1ee56c5e0

---

📥 Commits

Reviewing files that changed from the base of the PR and between 8c8c9ec and b8a9677.

---

📒 Files selected for processing (4)

• apps/timo-web/components/modal/OverlayModal.tsx
• packages/timo-design-system/src/components/layout/modal/Modal.tsx
• packages/timo-design-system/src/lib/index.ts
• packages/timo-design-system/src/lib/modal-stack-registry.ts

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Storybook Preview

항목	링크
Storybook	열기
Chromatic 빌드	확인

마지막 업데이트: 2026-10-10 14:41 UTC

[github-actions]

Timo Performance Report

Bundle Size — timo-web

라우트	크기	First Load JS
/[locale]/home	277.93 kB	🔴 483.75 kB
/[locale]/today	262.19 kB	🔴 468.00 kB
/[locale]/focus	223.50 kB	🔴 429.31 kB
/[locale]/settings	230.03 kB	🔴 435.84 kB
/[locale]/statistics	211.84 kB	🔴 417.65 kB
/[locale]/[...rest]	0 B	🟡 205.81 kB
/[locale]/login	282.60 kB	🔴 488.42 kB
/[locale]/oauth/calendar/callback	121.38 kB	🟡 327.19 kB
/[locale]/oauth/callback	121.04 kB	🟡 326.85 kB
/[locale]/onboarding	295.41 kB	🔴 501.23 kB
/[locale]	120.35 kB	🟡 326.17 kB
/[locale]/policy	121.32 kB	🟡 327.14 kB
/robots.txt/route	0 B	🟡 205.81 kB
/sitemap.xml/route	0 B	🟡 205.81 kB

공유 번들: 205.81 kB
🟢 < 200kB  |  🟡 < 350kB  |  🔴 ≥ 350kB (First Load JS · gzip)

Lighthouse — timo-web

URL	Perf	A11y	LCP	CLS	TBT
/en/home	🔴 63	🟢 96	🔴 16.4s	🟢 0.000	🟡 457ms
/en/today	🔴 61	🟢 96	🔴 16.3s	🟢 0.000	🟡 523ms
/en/focus	🔴 63	🟢 96	🔴 16.1s	🟢 0.000	🟡 442ms
/en/statistics	🔴 64	🟢 96	🔴 16.1s	🟢 0.000	🟡 405ms

Perf ≥ 70 / A11y ≥ 85 목표
LCP 🟢 < 2.5s 🟡 < 4s 🔴 ≥ 4s  |  CLS 🟢 < 0.1 🟡 < 0.25 🔴 ≥ 0.25  |  TBT 🟢 < 200ms 🟡 < 600ms 🔴 ≥ 600ms

Image Optimization — timo-web

파일	크기	포맷	상태
favicon.png	27.84 kB	PNG ⚠️	🟢
images/google-calendar.png	36.20 kB	PNG ⚠️	🟢
images/google-logo.png	26.79 kB	PNG ⚠️	🟢
og.png	437.44 kB	PNG ⚠️	🟡

총 4개 · 528.28 kB  |  🟢 < 200KB  |  🟡 < 500KB  |  🔴 ≥ 500KB
⚠️ 4개 파일 WebP/AVIF 변환 권장

측정 커밋: 27a5dfe

[ehye1]

와우 이런 문제는 어떻게 찾으셨나요? 덕분에 z-index에 대해서 더 배우게 됐습니다. 굿굿

[jjangminii]

와우 이런 문제는 어떻게 찾으셨나요? 덕분에 z-index에 대해서 더 배우게 됐습니다. 굿굿

코드리뷰 하다가 엣지 케이스를 발견했어요..😢 앱잼 때 제가 급하게 작성하느라 미처 확인하지 못했던 부분이더라고요.

[yumin-kim2]

이번 PR 보면서 정말 많이 배웠어요…! 저는 모달이 잘 뜨고 닫히는지만 확인해서, 내부적으로 z-index 값이 계속 증가하고 있다는 건 미처 생각하지 못했던 것 같아요. 개발자 도구로 직접 확인해 보니까 수정 전에는 계속 올라가던 값이 수정 후에는 50으로 유지돼서 신기했어요!! 👀

궁금해서 더 공부해 봤는데 이렇게 값이 계속 누적되면 쌓임 맥락에 따라 고정된 z-index를 쓰는 토스트까지 가릴 수 있다고 하더라고요. 눈에 보이는 화면뿐 아니라 내부 값이 반복 사용하면서 어떻게 변하고 다른 요소에 어떤 영향을 주는지도 고려해야 한다는 걸 배웠습니다!! 👍👍💕