`Overlay` component can cause layout shift when used with focusable component

[yangwooseong]

Summary

Overlay 컴포넌트가 TextField 같이 포커스 가능한 컴포넌트와 같이 사용될 때 레이아웃이 시프트 되는 버그가 있습니다.

Reproduction process

재현 방법

1. container 로 지정한 엘리먼트의 경계에 가까이 오버레이를 위치시킵니다.
2. 오버레이안에 너비가 넓은 TextField 컴포넌트를 사용하고 autoFocus 속성을 true로 줍니다.
3. 오버레이를 열때마다 간헐적으로 레이아웃이 시프트됩니다.

2025_03_28_05_10_PM_1743149420.mp4

원인

오버레이를 띄울 때 2단계에 걸쳐서 보여주면서 transform 속성이 짧은 순간에 바뀌는 것이 원인입니다.

bezier-react/packages/bezier-react/src/components/Overlay/Overlay.tsx

Lines 194 to 263 in 32c5e51

	/**
	* Case 1: show === true
	* show -> shouldRender -> shouldShow
	* shouldRender 를 true 로 설정하고, 직후에 shouldShow 를 true 로 설정하여 transition 유발
	*
	* Case 2: show === false
	* show -> shouldShow -> (...) -> shouldRender
	* shouldShow 를 false 로 설정하고, shouldRender 는 transition 필요 여부에 따라 다르게 결정함
	* Case 2-1: withTransition === true
	* shouldShow -> onTransitionEnd -> shouldRender
	* onTransitionEnd handler 를 이용해 transition 이 끝난 다음 shouldRender 를 false 로 설정
	* Case 2-2: withTransition === false
	* shouldShow && shouldRender
	* transition 을 기다릴 필요가 없으므로 바로 shouldRender 를 false 로 설정
	*/
	useEffect(() => {
	if (show) {
	if (shouldRender) {
	window.requestAnimationFrame(() => setShouldShow(true))
	} else {
	window.requestAnimationFrame(() => setShouldRender(true))
	}
	}
	if (!show) {
	window.requestAnimationFrame(() => setShouldShow(false))
	if (!withTransition) {
	window.requestAnimationFrame(() => setShouldRender(false))
	}
	}
	}, [show, withTransition, shouldRender, shouldShow, window])
	const themeName = useThemeName()
	if (!shouldRender) {
	return null
	}
	const Content = (
	<ThemeProvider themeName={themeName}>
	<div
	className={classNames(
	styles.Overlay,
	!shouldShow && styles.hidden,
	withTransition && styles.transition,
	className
	)}
	style={{
	...style,
	...getOverlayStyle({
	containerRect: containerRect.current,
	targetRect: targetRect.current,
	overlay: overlayRef.current,
	position,
	marginX,
	marginY,
	keepInContainer,
	show: shouldShow,
	}),
	}}
	ref={mergedRef}
	data-testid={OVERLAY_TEST_ID}
	onTransitionEnd={handleTransitionEnd}
	{...rest}
	>
	{children}
	</div>
	</ThemeProvider>
	)

1. shouldRender = true, shouldShow = false
   getOverlayStyle 가 호출될 때 overlayRef 가 아직 null 인 상태이기 때문에 getOverlayStyle 의 결과로 transform: translateX(0px) translateY(0px) 이 나오게 되고, opacity: 0 인 상태로 target 바로 위에 오버레이가 뜹니다. 사용자에는 아직 보이지 않지만 DOM 에 마운트는 되어 있는 상태입니다.

2. shouldRender = true, shouldShow = true
   overlayRef 가 엘리먼트를 참조한 상태이기 때문에 getOverlayStyle이 오버레이의 position 속성에 따라 적절한 translate 값을 반환하게 되고, 그 결과 오버레이 위치가 바뀌면서 사용자에게 보이게 됩니다.

이렇게 2단계에 걸치는 렌더링은 대부분의 경우에는 문제가 안되지만, TextField 컴포넌트처럼 autoFocus 할 수 있는 요소와 같이 쓰면 첫 번째 단계에서 포커스 되면서 스크롤이 움직이게 됩니다.

제안

장기적으로는 floating-ui 같은 외부 라이브러리를 사용해서 리팩토링 하면 좋겠으나, 지금 당장에 간단하게 고치려면 첫 번째 단계 렌더링때 inert 속성을 활용해서 포커싱을 못하게 하면 될 것 같습니다. 사파리 호환성이 15.4 이상이어야 하는 점이 걸리는데, browserlist 에서 15.4 이상을 명시하고 있기 때문에 상관 없을 것 같기도 하네요. 혹시 어떻게 생각하시나요? @sungik-choi

Version of bezier-react

3.1.0

Browser

No response

Operating system

• macOS
• Windows
• Linux

Additonal Information

No response

[channeltalk]

https://desk.channel.io/#/channels/1/team_chats/groups/1237/67e65de50ed1e2bffc4c

[sungik-choi]

장기적으로는 floating-ui 같은 외부 라이브러리를 사용해서 리팩토링 하면 좋겠으나, 지금 당장에 간단하게 고치려면 첫 번째 단계 렌더링때 inert 속성을 활용해서 포커싱을 못하게 하면 될 것 같습니다. 사파리 호환성이 15.4 이상이어야 하는 점이 걸리는데, browserlist 에서 15.4 이상을 명시하고 있기 때문에 상관 없을 것 같기도 하네요. 혹시 어떻게 생각하시나요? @sungik-choi

말씀주신대로 이미 사파리 15.4 버전 이상만 지원하고 있기때문에 문제 없어보여요

[yangwooseong]

다시 생각해보니 inert=true -> inert=false 로 하는 방법도 완벽하지는 않네요.
단순히 inert={!overlayRef.current} 로 하게 되면 오버레이안에서 autoFocus 를 하더라도 마운트 시점에서는 inert={true}라서 autoFocus가 동작하지 않는 이슈가 생깁니다. 그렇다고 overlayRef.current 에 따라서 inert={true}인 Content 와 inert={false} 인 Content를 각각 마운트하게 되면 inert={false}인 Content가 마운트될때 autoFocus 는 잘 동작하지만, children 이 2번 마운트 되서 사이드 이펙트가 생길 수 있습니다.
지금처럼 2단계에 걸친 렌더링 방식을 바꿔야 근본적인 해결이 가능해 보입니다. 아예 radix Popover 를 써서 재구현을 해야할지 고민되는 부분입니다.

[sungik-choi]

다시 생각해보니 inert=true -> inert=false 로 하는 방법도 완벽하지는 않네요. 단순히 inert={!overlayRef.current} 로 하게 되면 오버레이안에서 autoFocus 를 하더라도 마운트 시점에서는 inert={true}라서 autoFocus가 동작하지 않는 이슈가 생깁니다. 그렇다고 overlayRef.current 에 따라서 inert={true}인 Content 와 inert={false} 인 Content를 각각 마운트하게 되면 inert={false}인 Content가 마운트될때 autoFocus 는 잘 동작하지만, children 이 2번 마운트 되서 사이드 이펙트가 생길 수 있습니다. 지금처럼 2단계에 걸친 렌더링 방식을 바꿔야 근본적인 해결이 가능해 보입니다. 아예 radix Popover 를 써서 재구현을 해야할지 고민되는 부분입니다.

말씀주신대로 마운트가 2회 수행되기도하고, overlay dom node가 존재하지 않는 경우에도 불필요하게 Content를 렌더하게되어 해당 방식으로 해결하지 못할 거 같네요. 사용자 입장의 동작을 바꾸지 않는 선에서 렌더링 로직을 재구현하는게 가장 좋아보입니다