소개

Viewake는 한 가지 명확한 규칙을 가진 등장 애니메이션 라이브러리입니다.

잠든 요소가 자신의 뷰포트 아래에서 들어올 때만 애니메이션을 시작합니다.

일반적인 등장 라이브러리는 요소가 화면과 겹치는지만 판단합니다. 그러면 요소가 화면 위로 나간 경우와 아래로 나간 경우를 구별하기 어렵습니다. Viewake는 현재 위치뿐 아니라 요소의 상태도 함께 보존합니다.

두 가지 상태

sleeping → awake

• sleeping: 요소가 화면 아래에 있고 등장할 준비가 된 상태
• awake: 요소가 이미 등장하여 보이는 상태

초기화할 때 이미 화면 안이나 화면 위에 있는 요소는 awake로 시작합니다. SSR hydration 도중 콘텐츠가 숨겨지거나, 중간 위치에서 페이지를 열었을 때 갑자기 애니메이션이 실행되는 일을 막기 위한 규칙입니다.

mirror 모드가 없는 이유

Viewake는 요소가 화면 위로 지나갔다고 해서 퇴장 애니메이션으로 숨기지 않습니다. 사용자가 읽던 콘텐츠는 스크롤 중에도 안정적으로 보여야 하기 때문입니다.

replay의 재설정은 사용자가 요소보다 위로 돌아가 요소가 화면 아래에 완전히 놓인 뒤에만 일어납니다. 이때 요소는 이미 보이지 않는 곳에 있으므로 사용자는 상태가 sleeping으로 바뀌는 장면을 보지 않습니다.

브라우저에서 동작하는 흐름

Viewake는 매 스크롤마다 실행되는 이벤트 리스너 대신 IntersectionObserver를 사용하고, 실제 opacity와 transform 변화는 CSS에 맡깁니다.

IntersectionObserver
        ↓ 위치와 교차 여부
sleeping / awake 상태 머신
        ↓
pending / active data 상태
        ↓
CSS transition

IntersectionObserver는 브라우저가 계산한 교차 정보를 비동기로 전달합니다. 따라서 직접 scroll 이벤트에서 매번 getBoundingClientRect()를 호출하는 구현보다 레이아웃 계산을 덜 유발하고 책임도 명확합니다.

설계 목표

• 스크롤 방향에 따라 예측 가능한 동작
• JavaScript가 없어도 보이는 콘텐츠
• SSR 환경에서 안전한 import
• 프레임워크에 종속되지 않는 작은 코어
• 명시적인 생성·관찰·정리 생명주기
• 사용자의 모션 감소 설정 존중

Viewake의 JavaScript가 시각 스타일을 직접 설정하지 않는 이유는 data 속성 사용법에서 자세히 설명합니다.

학습 완료 조건

이 문서를 이해했다면 다음을 설명할 수 있어야 합니다.

• 단순한 isIntersecting 검사만으로 위·아래 이탈을 구별할 수 없는 이유
• 처음부터 화면 위나 안에 있는 요소를 awake로 만드는 이유
• Viewake에서 JavaScript와 CSS가 각각 담당하는 역할