1. 증상- 분명 보냈는데 운동강도가 계속 0에서 변경되지 않아요.

운동 시작 버튼을 누르면 아래 두 가지가 STM32 제어 보드로 전송되어야 합니다.

1. 운동강도 파라미터 패킷

2. 운동 시작을 지시하는 상태 명령 패킷(state = 4)

하지만, Web 버전에서는 정상 동작하는 운동시작 데이터 전송 과정이, Android 이식 이후, 부하가 초기값인 0에서 변동되지 않고 운동이 시작되는 이슈가 있었습니다.

로그를 보면 두 패킷 모두 의도했던 50byte 크기로 전송되는 것을 확인할 수 있습니다. 전송 자체는 성공인데, STM이 부하를 인식하지 못하는 상황입니다.

I/StmSerialManager: paramTransmitToSTM: 5.0, 5.0, 5.0, 5.0, 5.0, 99.0, ...
I/StmSerialManager: Sent 50 bytes
I/StmSerialManager: sendStateCommand: 4
I/StmSerialManager: Sent 50 bytes

“프로토콜이 다른 건 아닐까?” 의심이 들어, 두 플랫폼 간 프로토콜을 바이트 단위로 비교한 결과, 두 패킷 모두 차이가 없어 원인이 아님을 확인했습니다.

2. 원인 추적: 비동기 전송과 Race Condition

그 이후, 운동 시작 간 2개의 패킷을 전송하는 것이기에, 보내는 시점 차이가 변수가 될 수 있다고 판단하였습니다.

2.1 scope.launch의 함정

Android의 USB Host api 내부 bulkTransfer는 응답을 기다려야 하는 블로킹 작업, 즉 호출한 스레드가 결과를 받을 때까지 멈춰 다른 일을 할 수 없는 작업입니다. 때문에 이를 메인스레드에서 호출할 경우, UI가 멈추는 freezing 현상으로 이어지기에 코루틴으로 백그라운드에서 처리합니다.

*여기서 코루틴은 suspend 및 resume이 가능한 경량 실행 단위입니다.

문제는 Kotlin의 scope.launch는 작업을 백그라운드 스레드풀에 맡기고 즉시 반환하며, 이로 인해 scope.launch를 여러번 호출하면 독립된 코루틴들이 동시에 실행되어 순서가 보장되지 않는 Race Condition이 발생할 수 있다는 것입니다.

scope.launch { bulkTransfer(outEndpoint, packet1, 50, 1000) }  // 즉시 반환
scope.launch { bulkTransfer(outEndpoint, packet2, 50, 1000) }  // 즉시 반환

2.2 Race Condition 사례

Race Condition이란, 둘 이상의 작업이 공유 자원에 접근할 때 실행 순서에 따라 결과가 달라지는 버그입니다. 우리 코드에서는 이렇게 나타났습니다.

운 좋을 때:

코루틴A: 부하 패킷 전송 → 완료
코루틴B: 상태 패킷 전송 ──────→ 완료
STM 수신: [부하=5.0] → [상태=Running] → 부하 5.0으로 모터 구동 ✅

운 나쁠 때:

코루틴A: 부하 패킷 전송 ──────→ 전송 중…
코루틴B: 상태 패킷 전송 ──→ 전송 완료!
STM 수신: [상태=Running] → 부하가 아직 안 왔는데 Running!

→ 기본값(0)으로 구동 ❌

Web에서는 Node.js 기반 serialPort 라이브러리가 write 작업을 FIFO 큐로 직렬화 하고 있었으나, Android에서는 별도 라이브러리를 사용하지 않았기에 순서 보장 매커니즘이 부재한 것이었습니다.

3. 고민하였던 동시성 제어 패턴들

3.1 Mutex (상호 배제)

Mutex = 화장실 열쇠

    코루틴A: "열쇠 주세요" → 획득 → [전송 중...] → 반납
                                                   ↓
    코루틴B:              "열쇠 주세요" → 대기... → 획득 → [전송 중...] → 반납

한 번에 하나의 코루틴만 공유 자원(USB 포트)에 접근할 수 있는 패턴입니다.

private val mutex = Mutex()

scope.launch {
    mutex.withLock {
        bulkTransfer(packet)  // 이 안에서는 다른 코루틴이 끼어들 수 없음
    }
}

장점: 구현이 간단
단점: 두 코루틴이 거의 동시에 launch되면, 어느 것이 먼저 lock을 잡을지는 여전히 불확정 -> 순서 보장이 아니라 “상호 배제”만 제공.

3.2 Channel(채널 기반 큐)

이는 iOS에서 사용되는 DispathQueue와 유사합니다.

Channel = 편의점 번호표 시스템

    손님A가 번호표 1번 뽑음 → [대기열: 1]
    손님B가 번호표 2번 뽑음 → [대기열: 1, 2]
                                     ↓
    직원이 1번 호출 → A 처리 → 2번 호출 → B 처리

패킷을 Channel(큐)에 넣으면, 단일 소비자 코루틴이 넣은 순서대로(FIFO) 하나씩 꺼내서 전송합니다.

// 생산자: 패킷을 큐에 넣기만 함 (즉시 반환)
sendChannel.trySend(packet1)  // → [큐: packet1]
sendChannel.trySend(packet2)  // → [큐: packet1, packet2]

// 소비자: 단일 코루틴이 순서대로 처리
scope.launch {
    for (packet in sendChannel) {
        bulkTransfer(packet)  // packet1 먼저, 그다음 packet2
    }
}

장점: 삽입 순서가 곧 처리 순서. FIFO 보장.
단점: 채널 관리(생성, 소멸) 필요

3.3 순차 코루틴 (Sequential Coroutine)

scope.launch {
    bulkTransfer(packet1)  // 완료될 때까지 대기
    delay(100)             // STM 처리 시간 확보
    bulkTransfer(packet2)  // 그 다음 실행
}

장점: 가장 직관적

단점: 호출 측에서 매번 순서를 관리해야 함. 여러 곳에서 sendCommand를 호출하면 일관성 유지가 어려움.

3.4 왜 Channel을 선택했는가?

초기에는 순차 코루틴을 시도했습니다. 하지만, 호출하는 곳마다 2개의 명령어를 하나의 코루틴으로 묶는 작업을 직접 관리해야했습니다. 이는 호출부가 늘어날 수록 휴먼 에러로 이어질 확률이 높아진다고 판단했습니다.

하지만, Channel방식은 sendCommand 내부에서 큐에 넣는 작업으로 대체하기만 하면, 호출 위치 상관없이 순서 보장 및 상호배제가 이뤄지기 때문에 Channel을 통한 제어 패턴을 최종 선택하였습니다.

4. 수정 적용

변경 1: 전송 채널 선언

// 수정 전:
private val scope = CoroutineScope(Dispatchers.IO)
private var readJob: Job? = null

// 수정 후:
private val scope = CoroutineScope(Dispatchers.IO)
private var readJob: Job? = null
private var sendJob: Job? = null
private val sendChannel = Channel<ByteArray>(Channel.UNLIMITED)

변경 2: 단일 소비자 코루틴 시작 (startSendLoop)

fun initialize() {
    // ... (기존 코드) ...
    startSendLoop()    // ← 추가
    scanAndConnect()
}

private fun startSendLoop() {
    sendJob?.cancel()
    sendJob = scope.launch {
        for (packet in sendChannel) {
            val ep = outEndpoint
            if (ep == null) {
                Log.e(TAG, "Send failed: no OUT endpoint")
                continue
            }
            val sent = usbConnection?.bulkTransfer(ep, packet, packet.size, 1000) ?: -1
            if (sent < 0) {
                Log.e(TAG, "Send failed: bulkTransfer returned $sent")
            } else {
                Log.d(TAG, "Sent $sent bytes")
            }
        }
    }
}

변경 3: sendCommand에서 직접 전송 → 채널 큐잉으로 교체

// 수정 전:
private fun sendCommand(...) {
    // ... (패킷 구성) ...
    scope.launch {  // ← 매번 새 코루틴 = 순서 보장 안 됨
        usbConnection?.bulkTransfer(ep, packet, packet.size, 1000)
    }
}

// 수정 후:
private fun sendCommand(...) {
    // ... (패킷 구성) ...
    sendChannel.trySend(packet)  // ← 큐에 넣기만 함. 순서 보장됨.
}

5. 교훈

교훈 1: scope.launch는 “보내기”가 아니라 “부탁하기”입니다…

scope.launch { bulkTransfer(packet) }

이 코드는 “패킷을 보내라”가 아니라 “패킷을 보내달라고 스레드풀에 부탁하는 것”입니다. 호출한 순서대로 처리된다고 가정하였으나, 스레드풀의 스케줄링에 따라 순서가 뒤바뀔 수 있음을 이번 디버깅 경험을 통해 깨달았습니다.

교훈 2: Race Condition은 로그로 잡기 어렵다

I/StmSerialManager: paramTransmitToSTM: 5.0, 5.0, ...
I/StmSerialManager: sendStateCommand: 4
I/StmSerialManager: Sent 50 bytes
I/StmSerialManager: Sent 50 bytes

교훈 1과 맥락을 같이하는 교훈인데요. 위 로그를 보면 실제 운동강도 전달 로직 (paramTransmitToSTM)이 먼저 실행된 것처럼 보이지만, 이는 실제 USB 버스에 올라간 시점이 아닌 호출 자체가 이뤄진 시점입니다. 때문에, Race Condition을 의심할 때는 코드 레벨에서 이를 검증해야합니다.

감사합니다.

*보안상 전체 코드는 따로 공유하고 있지 않은 점 양해 부탁드립니다.

1. 배경- 우리가 만들고 있는 것

저희가 담당하고 있는 프로젝트는 “운동 기구를 제어하는 태블릿 앱” 입니다.

• 태블릿 앱: 사용자에게 운동 화면을 보여주고, 운동 시작/중지 명령을 보냄
• STM32 보드: 실제 모터를 제어하고, 페달 속도/힘/파워 데이터를 실시간으로 보내줌

이 둘은 USB 케이블로 연결되어 50바이트짜리 데이터 패킷을 주고받습니다.

기존 웹 버전- serialport 한 줄이면 끝

원래 이 시스템은 Windows PC + Electron 웹앱으로 동작하고 있었습니다.

Node.js의 serialport라이브러리를 사용해서 COM12 포트에 연결하면 끝이었습니다. 운영체제가 USB 디바이스를 “시리얼 포트”로 자동 인식해주기 때문에, 개발자는 복잡한 USB 프로토콜을 신경 쓸 필요가 없었습니다.

Android로 이식하기- 그리고 마주친 현실

기존 Windows PC + Electron 구성에는 두 가지 한계가 있었습니다.

• 설치/유지보수 부담
  - PC는 Windows 업데이트, 드라이버 관리, 장애 대응이 필요
  - 태블릿은 앱 하나 설치하면 끝, 키오스크 모드로 잠그면 사용자가 건드릴 것도 없음
• 사용자 경험
  - 드래그 동작에 대한 대응 미비
  - 안드로이드의 경우, 기존 디자인 시스템 활용으로 플랫폼 확장에 용이

그래서 Android 태블릿 전용 앱으로 만들기로 했습니다.

그런데 막상 이식을 시작하니, 웹에서는 없던 문제가 나타났습니다. Android에서는 Node.js의 serialport같은 편리한 라이브러리가 없고, 대신 Android USB Host API를 사용해서 직접 USB 디바이스와 통신해야 했습니다.

웹에서는 OS가 모든 복잡성을 처리해줬지만, Android에서는 앱이 직접 USB 프로토콜의 모든 단계를 처리해야 합니다.

이 글에서는 Android USB Host API로 통신을 구현하는 전체 과정과, 그 과정에서 만난 이슈들을 다룹니다.

2. USB 통신의 기본 개념

구현에 앞서, USB 통신의 핵심 개념을 짚고 가겠습니다.

2.1 USB 디바이스 = 아파트 건물

USB 디바이스 하나를 빌라건물이라고 생각해볼까요??

• Interface = 빌라의 각 호수
• 각 호수에는 다른 기능이 하나씩 살고 있습니다 (시리얼 통신, 저장장치, 디버그 등)

2.2 Endpoint = 우편함

각 호수(Interface)에는 우편함(Endpoint)이 있습니다.

• IN Endpoint: 디바이스 → 호스트 (STM32 → 태블릿) 방향
• OUT Endpoint: 호스트 → 디바이스 (태블릿 → STM32) 방향

여기서 IN/OUT은 호스트(태블릿) 관점입니다.
IN = “태블릿으로 들어오는”, OUT = “태블릿에서 나가는”

2.3 Claim = 열쇠 받기

아파트 호수를 사용하려면 열쇠(Claim)를 받아야 합니다.

태블릿 앱: 3호(Interface 3) 쓰고 싶습니다
Android 운영체제: “네, 여기 열쇠요” (claimInterface → true)
태블릿 앱: (열쇠로 문 열고 우편함 사용)

만약 다른 누군가(커널 드라이버)가 이미 그 호수를 쓰고 있다면?

태블릿 앱: “3호 쓰고 싶습니다”
Android 운영체제: “안 됩니다, 이미 다른 사람이 쓰고 있어요” (claimInterface → false)
태블릿 앱: (우편함 사용 불가 = Send failed)

2.4 USB Class Code = 호수별 용도 표지판

빌라 각 호수에는 용도 표시판이 붙어있습니다. 이는 USB 표준 기구(USB-IF)가 정한 국제 표준 번호로, 어떤 기기든 동일한 규칙을 따릅니다.

CDC ACM(Abstract Control Model) 시리얼 통신에서는 Class 2 + Class 10이 반드시 한 쌍으로 동작합니다.

• Class 2 (CDC Communication): “115200 baud로 통신하자”고 약속하는 제어 채널
• Class 10 (CDC Data): 실제 데이터가 흐르는 데이터 채널

이 Class 번호는 USB 규격서에 명시된 표준이기 때문에, STM32든 Arduino든 ESP32든 CDC ACM을 구현하면 항상 이 번호를 사용합니다.

*단, 제조사가 CDC 표준을 쓰지 않고 Class 255 (Vendor-Specific)로 자체 시리얼 프로토콜을 구현하는 경우도 있습니다. 이 경우에는 Class 10이 아예 없고, 제조사 문서를 봐야 합니다.

2.5 CDC ACM 드라이버 = 자동 번역기

CDC ACM 드라이버는 USB 시리얼 통신을 처리하는 운영체제의 커널 드라이버입니다. USB 디바이스가 연결되면, OS 커널이 “Class 2+10이 있네? CDC ACM이구나!” 하고 이 드라이버를 자동으로 붙여서 가상 시리얼 포트를 만들어줍니다.

1. USB 디바이스 연결

2. 커널: “Interface Class 2+10 발견 → CDC ACM이구나”

3. cdc_acm 드라이버 자동 로드

4. 가상 시리얼 포트 생성

- Windows: COM12
- Linux: /dev/ttyACM0
- Mac: /dev/tty.usbmodem…

Windows PC에서 COM12로 편하게 통신할 수 있었던 건 이 드라이버 덕분이었습니다. 그렇다면 Android에서도 이 드라이버가 만든 /dev/ttyACM0을 직접 사용하면 되지 않을까요?

이는 Android의 권한 시스템 때문에 불가능합니다.

루팅된 기기나 시스템 앱이 아닌 이상, 일반 앱은 이 파일에 접근할 수 없습니다.그래서 Android는 USB Host API라는 별도 경로를 제공합니다.

USB 호스트 개요 | Connectivity | Android Developers

커널 드라이버 경로 (일반 앱은 사용 불가)

앱 → /dev/ttyACM0 → cdc_acm 드라이버 → USB → STM32
❌ Permission Denied

USB Host API 경로 (우리가 사용하는 방법)

앱 → UsbManager → USB 권한 팝업 → 사용자 승인 → 직접 통신 → STM32
✅ 사용자가 권한 승인하면 OK

USB Host API는 커널 드라이버를 우회해서 앱이 직접 USB 디바이스와 통신하는 방법입니다. 대신 커널 드라이버가 해주던 모든 것(Interface 탐색, claim, CDC 초기화 등)을 앱이 직접 구현해야 합니다.

2.6 커널 드라이버 = 자동 입주 시스템

Android(Linux)에는 자동 입주 시스템이 있습니다. USB 디바이스가 연결되면, 운영체제의 커널이 자동으로 “아, 이건 시리얼 디바이스구나!” 하고 해당 Interface에 드라이버를 자동으로 붙여버립니다 (마치 관리소가 빈 방에 자동으로 세입자를 넣는 것처럼).

여기서 문제가 하나 발생합니다. 커널의 드라이버 바인딩은 USB가 물리적으로 연결되는 순간 바로 발생하는데, USB Host api를 통한 claim 작업은 앱에서 openDevice()를 호출한 이후에나 진행됩니다.

즉 커널 드라이버 바인딩과 openDevice() 사이에는 브로드캐스트 수신 + 권한 요청 + 사용자 승인이라는 여러 단계가 끼어 있어서, 커널이 항상 먼저 점유하게 됩니다.

3. 우리 STM32 디바이스의 구조

구현에 앞서 저희가 데이터 통신을 진행하게 될 STM32 제어보드의 구조를 파악하고자 했습니다. 디버깅 로그를 통해 확인한 우리 STM32 디바이스의 실제 구조입니다.

USB Device: VID=0x0483 (STMicroelectronics), PID=0x374E

┌─── Interface 0 ──────────────────────────┐
│ Class: 255 (Vendor-Specific, 제조사 고유)   │
│ Endpoints: 3개                            │
│   EP0: BULK IN  (addr=0x81, 512 bytes)   │
│   EP1: BULK OUT (addr=0x01, 512 bytes)   │
│   EP2: BULK IN  (addr=0x82, 512 bytes)   │
│ → 제조사가 임의로 만든 인터페이스            │
└──────────────────────────────────────────┘

┌─── Interface 1 ──────────────────────────┐
│ Class: 8 (Mass Storage, USB 저장장치)      │
│ Endpoints: 2개                            │
│   EP0: BULK IN  (addr=0x83, 512 bytes)   │
│   EP1: BULK OUT (addr=0x03, 512 bytes)   │
│ → USB 메모리처럼 파일 저장용               │
│ → 우리와 무관                              │
└──────────────────────────────────────────┘

┌─── Interface 2 ──────────────────────────┐
│ Class: 2 (CDC Communication, 시리얼 제어)  │
│ Endpoints: 1개                            │
│   EP0: INTERRUPT IN (addr=0x84, 10 bytes)│
│ → 시리얼 포트의 "제어 채널"                │
│ → 보드레이트 설정, DTR/RTS 신호 등          │
└──────────────────────────────────────────┘

┌─── Interface 3 ──────────────────────────┐
│ Class: 10 (CDC Data, 시리얼 데이터)        │
│ Endpoints: 2개                            │
│   EP0: BULK OUT (addr=0x05, 512 bytes)   │
│   EP1: BULK IN  (addr=0x85, 512 bytes)   │
│ → 실제 시리얼 데이터가 오가는 곳 ✅         │
│ → 이 Endpoint를 사용해야 함                │
└──────────────────────────────────────────┘

이 디바이스는 Composite USB Device (복합 USB 디바이스)입니다. 하나의 USB 장치 안에 여러 기능(시리얼, 저장장치, 제조사 고유 기능)이 함께 들어있습니다.

시리얼 통신에 필요한 것은 Interface 2 (CDC Comm, 제어) + Interface 3 (CDC Data, 데이터)조합입니다.

4. 구현 Step 1- 올바른 Interface와 Endpoint 찾기

첫 번째 시도: Interface 0번 고정

처음 작성한 코드는 아주 단순했습니다.

// "무조건 Interface 0번의 Endpoint를 사용한다"
val intf = device.getInterface(0)
usbConnection?.claimInterface(intf, true)

// Interface 0에서 IN/OUT Endpoint를 찾는다
val endpoint = (0 until intf.endpointCount)
    .map { intf.getEndpoint(it) }
    .firstOrNull { it.direction == USB_DIR_OUT }

이 코드는 Interface 0 (class=255, Vendor-Specific)의 Endpoint를 사용했습니다.

태블릿 앱 > [Interface 0, addr=0x01] > STM32
❌ 이건 시리얼이 아님!

비유하자면, 시리얼 통신 우편함은 3호(Interface 3)에 있는데, 1호(Interface 0)의 우편함에 편지를 넣은 것입니다.

이슈: bulkTransfer returned -1

Interface 0의 Endpoint로 데이터를 보내면, STM32는 이를 시리얼 데이터로 인식하지 않습니다.

결과는 Send failed: bulkTransfer returned -1

Interface 0(Vendor-Specific)에도 BULK IN/OUT Endpoint가 있어서 겉보기에는 비슷해 보이지만, 실제 용도가 다릅니다. Class Code를 확인해야 하는 이유입니다.

해결: Class Code 기반 동적 탐색

// Interface를 분류한다
for (i in 0 until device.interfaceCount) {
    val intf = device.getInterface(i)
    if (intf.interfaceClass == 2) cdcCommInterface = intf   // 시리얼 제어
    if (intf.interfaceClass == 10) cdcDataInterface = intf  // 시리얼 데이터 ✅
    if (intf.interfaceClass == 255) vendorInterface = intf  // 제조사 고유
}

// CDC Data를 최우선으로 시도
val interfacesToTry = listOfNotNull(cdcDataInterface, vendorInterface)

이제 올바른 우편함(Interface 3, addr=0x05/0x85)을 사용하게 되었습니다:

태블릿 앱 > [Interface 3, addr=0x05] > STM32
✅ CDC Data = 시리얼 통신

5. 구현 Step 2- 커널 드라이버 분리 및 Interface Claim

올바른 Interface를 찾았으니, 다음은 claim(열쇠 받기)입니다.

이슈: 모든 Interface에서 claim 실패

Interface 0: class=255, endpoints=3, claimed=false
Interface 1: class=8,   endpoints=2, claimed=false
Interface 2: class=2,   endpoints=1, claimed=false
Interface 3: class=10,  endpoints=2, claimed=false  ← 여기도 실패!

모든 Interface에서 claim이 실패하고 있었습니다.

원인: 커널 드라이버 자동 점유

앞서 설명한 “자동 입주 시스템” 때문이었습니다. force=true는 “강제로 빼앗기”인데, 어떤 이유에서인지 강제 해제가 제대로 동작하지 않았습니다.

해결: ioctl로 커널 드라이버 직접 분리

Linux 커널에는 USBDEVFS_DISCONNECT라는 명령이 있습니다. 이 명령을 보내면 커널 드라이버를 강제로 분리할 수 있습니다. 따라서 아래와 같이 USB 디바이스의 모든 Interface 를 순회하면서, 각 Interface에 붙어있는 드라이버를 강제로 떼어내고, ioctl(input/output control) 시스템 콜을 통해 Linux에서 디바이스에게 드라이버를 분리하라는 고정된 명령코드(0x5516)로 구성된 시스템 콜을 실행시켰습니다.

private fun tryDetachKernelDriver(conn: UsbDeviceConnection) {
    val fd = conn.fileDescriptor  // USB 디바이스의 파일 디스크립터

    for (i in 0 until device.interfaceCount) {
        // USBDEVFS_DISCONNECT (0x5516) ioctl 호출

        // ifaceBytes: 어떤 Interface에서 분리할지 (0, 1, 2, 3...)에 대한 범위
        val ifaceBytes = ByteBuffer.allocate(4)  // 4바이트 공간 확보
            .order(ByteOrder.LITTLE_ENDIAN) // 바이트 순서는 작은쪽부터
            .putInt(i) // Interface 번호를 삽입
            .array() // byte[] 배열로 변환
        Os.ioctl(fdObj, 0x5516, ifaceBytes)
    }
}

ioctl은 커널 레벨 API라서 Kotlin의 Int를 그대로 못 넘기고, 커널이 기대하는 바이트 배열 형식으로 변환해야 합니다. Linux 커널은 Little Endian으로 정수를 읽으므로 Interface 3을 넘기는 경우 아래와 같이 인자가 구성되어 전달됩니다.

Int 값: 3
Little Endian 바이트: [0x03, 0x00, 0x00, 0x00]

6. 구현 Step 3- CDC 초기화 (SET_LINE_CODING)

Interface를 claim하고 Endpoint를 잡았으니, 마지막으로 CDC 시리얼 초기화가 필요합니다.

CDC ACM이란?

USB CDC ACM은 “USB로 시리얼 포트를 흉내내는” 표준 프로토콜입니다. 시리얼 포트에는 보드레이트(baud rate)라는 설정이 필요합니다.

보드레이트 = 1초에 몇 비트를 주고받을지 약속하는 것
115200 = 1초에 115,200 비트 전송

아래의 SET_LINE_CODING은 이 보드레이트를 설정하는 USB 제어 명령입니다.

// "나 115200 baud, 8데이터비트, 패리티 없음, 1정지비트로 통신할게"
val lineCoding = ByteBuffer.allocate(7).apply {
    putInt(115200)  // 보드레이트
    put(0)          // 정지비트: 1개
    put(0)          // 패리티: 없음
    put(8)          // 데이터비트: 8개
}

이슈: CDC 제어 전송 실패

SET_LINE_CODING (iface=0): -1     ← 실패!
SET_CONTROL_LINE_STATE (iface=0): -1  ← 실패!

원인: 잘못된 Interface 번호 (wIndex)

CDC 제어 명령에는 어떤 Interface에 대한 명령인지 알려주는 wIndex 파라미터가 있습니다.

*wIndex는 word Index를 의미합니다. 일반적으로 word의 크기는 아키텍처마다 상이하나, USB 규격에서는 OS, 아키텍처와 무관하게 항상 16비트입니다.

// 기존 코드: wIndex = 0 (Interface 0에 보냄)
conn.controlTransfer(0x21, 0x20, 0, 0, ...)

CDC Communication Interface는 Interface 2인데, wIndex=0으로 보내고 있었습니다.

해결: 올바른 Interface 번호 사용

// CDC Communication Interface의 실제 번호를 사용
conn.controlTransfer(0x21, 0x20, 0, cdcCommInterface.id, ...)
//                                   ↑ wIndex=2 ← 올바름!

최종 통신 흐름

[앱 시작]
  ↓
scanAndConnect()
  ↓
USB 디바이스 발견 (VID=0x0483, STM32)
  ↓
USB 권한 확인/요청
  ↓
openDevice() → USB 연결 열기
  ↓
ioctl(USBDEVFS_DISCONNECT) → 커널 드라이버 분리
  ↓
Interface 분류:
  - Interface 2 (CDC Comm) → 제어용
  - Interface 3 (CDC Data) → 데이터용
  ↓
claimInterface(3, force=true)
  ↓
Endpoint 선택: 
  - IN: 0x85 (STM32 → 태블릿)
  - OUT: 0x05 (태블릿 → STM32)
  ↓
SET_LINE_CODING(115200 baud, wIndex=2)
SET_CONTROL_LINE_STATE(DTR+RTS, wIndex=2)
  ↓
startReading() → 50바이트 패킷 수신 시작
  ↓
[통신 준비 완료]
  ↓
sendCommand() → bulkTransfer(OUT, 50bytes) → STM32 제어

9. 구현에서 배운 것들

“연결됨”과 “통신 가능”은 다르다
isConnected = true가 되었다고 해서 데이터를 주고받을 수 있는 건 아닙니다. USB 디바이스를 열고(openDevice), 올바른 Interface를 claim하고, 올바른 Endpoint를 선택하고, 필요한 초기화까지 모두 완료해야 비로소 통신이 가능합니다,,,

Composite USB 디바이스는 함정이 많다
우리 STM32 디바이스에는 4개의 Interface가 있었고, 그중 시리얼 통신에 사용해야 하는 것은 Interface 3(CDC Data)뿐이었습니다. Interface 0(Vendor-specific)에도 비슷하게 생긴 BULK Endpoint가 있어서 혼동하기 쉬웠습니다.

디바이스마다 다르다
같은 STM32 칩이라도 펌웨어 설정에 따라 USB 구조가 완전히 다를 수 있습니다. 또한 같은 Android 코드라도 MTK, Qualcomm, Samsung Exynos 등 SoC에 따라 USB 호스트 동작이 미묘하게 다를 수 있습니다. 때문에, 하드코딩보다는 동적 탐색을 통해 이러한 차이를 대응하고자 했습니다.

안녕하세요. 오늘은 compose 1.3.0부터 도입된 Modifier.Node 및 관련 API들을 활용하여 프로젝트에 범용적으로 사용되고 있는 CustomButton의 성능을 최적화한 과정을 공유드리고자 합니다.

0. 서론: Jetpack Compose 내부 구성

Jetpack Compose 프레임워크에서는 UI를 설계할때, 아래와 같이 각 api의 역할을 구분하고 있습니다.

Composable 함수: 무엇을 그리고자 할 것인지 명시
Modifier: 어떻게 컴포넌트를 꾸밀 것인지 명시

 Text(
      "안녕하세요",
      modifier = Modifier
          .padding(16.dp)      // 여백 추가
          .background(Color.Red) // 배경색
          .clickable { }        // 클릭 가능
  )
// 컴파일러가 아래 순서의 연결된 Element로 변환
// [padding] → [background] → [clickable]

여기서 Modifier는 체이닝(chaining) 구조로 각 Modifier들 간 .으로 연결되며, Jetpack 컴파일러는 이를 링크드 리스트처럼 순서대로 연결된 Element의 체인으로 변환합니다.

// 실제 .padding Modifier의 내부구현
@Stable
fun Modifier.padding(all: Dp) = this then PaddingElement(
    start = all,
    top = all,
    end = all,
    bottom = all,
    rtlAware = true,
    inspectorInfo = {
        name = "padding"
        value = all
    }
)

private class PaddingElement(...) : ModifierNodeElement<PaddingNode>() {
    override fun create(): PaddingNode {}
    override fun update(node: PaddingNode) {}
    override fun hashCode(): Int {}
    override fun equals(other: Any?): Boolean {}
    override fun InspectorInfo.inspectableProperties() {
        inspectorInfo()
    }
}

private class PaddingNode() : LayoutModifierNode, Modifier.Node() {
    override fun MeasureScope.measure(
        measurable: Measurable,
        constraints: Constraints
    ): MeasureResult {
        val horizontal = start.roundToPx() + end.roundToPx()
        val vertical = top.roundToPx() + bottom.roundToPx()

        val placeable = measurable.measure(constraints.offset(-horizontal, -vertical))

        val width = constraints.constrainWidth(placeable.width + horizontal)
        val height = constraints.constrainHeight(placeable.height + vertical)
        return layout(width, height) {
            if (rtlAware) {
                placeable.placeRelative(start.roundToPx(), top.roundToPx())
            } else {
                placeable.place(start.roundToPx(), top.roundToPx())
            }
        }
    }
}

즉, Modifier는 인터페이스이며, 실질적인 동작은 각 Element가 수행합니다.

그럼 여기서 Element 는 정확히 무엇일까요?

Modifier.Element는 Modifier 체인에서 하나의 기능 단위를 의미합니다.

설령 위 Text 컴포저블의 경우, 패딩을 담당하는 Element, 배경을 담당하는 Element 그리고 클릭 동작을 담당하는 Element가 존재하는 것이죠. 이처럼 각 Element는 단일 책임을 갖습니다.

1. Composed Modifier (기존 Modifier 방식)

Compose 초기에는 상태 관리가 필요한 Modifier들이 내부적으로 composed {} 패턴을 사용했습니다. 현재는 대부분 ModifierNodeElement 기반으로 마이그레이션되었지만, composed {}의 구조를 이해하는 것이 Modifier.Node의 도입 배경을 파악하는 데 도움이 됩니다.

// 이전 pointerInput 내부 구현코드. 
// 현재는 SuspendPointerInputElement의 Modifier.Node 방식으로 구현되어있습니다.
fun Modifier.pointerInput(key: Any?, block: suspend PointerInputScope.() -> Unit): Modifier =
  composed {   // ← 이것이 핵심
      val scope = remember { ... }
      // ...
  }

composed {} 블록 내부에는 remember, LaunchedEffect와 같은 Composable 함수가 호출됩니다.

@Composable
inline fun <T> remember(crossinline calculation: @DisallowComposableCalls () -> T): T =
    currentComposer.cache(false, calculation)
// currentComposer = 컴파일러가 주입한 $composer 파라미터에 접근하는 프로퍼티

@Composable
@NonRestartableComposable
@OptIn(InternalComposeApi::class)
fun LaunchedEffect() {
    val applyContext = currentComposer.applyCoroutineContext
    remember(key1, key2, key3) { LaunchedEffectImpl(applyContext, block) }
}

여기서 Composable 함수는 컴파일 시 숨겨진 $composer 파라미터가 주입되며, 이는 런타임이 Composition Phase에서 Composable 트리 순회 간 Group 마커 삽입, 비교 등에 활용됩니다.

// 작성한 코드
@Composable
fun Greeting() {
    Text("Hello")
}

// 컴파일러 변환 후 (개념적)
fun Greeting($composer: Composer, $changed: Int) {
    $composer.startRestartGroup(1234567)   // ← Slot Table에 그룹 기록
    if ($changed == 0 && $composer.getSkipping()) {
        $composer.skipToGroupEnd()
    } else {
        Text("Hello", $composer, ...)
    }
    $composer.endRestartGroup()?.updateScope { // ← recomposition 람다 저장
        Greeting($composer, $changed or 0b1)
    }
}

즉 Composable 함수의 실행 자체가 Slot Table 위에서 동작하는 만큼, 렌더링 파이프라인의 Composition 단계가 필수적입니다.

- 렌더링 파이프라인 (Composition>Layout>Draw) 중 1번째 단계에서 실행
- Slot Table에 상태 슬롯을 할당

일반적인 Composable 함수는 파라미터가 변경되지 않았으면 skip될 수 있습니다. 하지만 composed {}로 생성된 ComposedModifier는 내부에 lambda를 감싸고 있어 의미 있는 equals() 구현이 불가능합니다.

// ComposedModifier 내부 구조
  private class ComposedModifier(
      val factory: @Composable Modifier.() -> Modifier
  ) : Modifier.Element
  // lambda는 참조 비교만 가능 → equals()가 항상 false

Compose 런타임은 Recomposition 시 이전 Modifier와 새 Modifier를 equals()로 비교하여 변경 여부를 판단합니다. Composed Modifier는 equals()가 항상 false를 반환하므로, Recomposition이 발생할 때마다 composed 블록에 반드시 재진입하여 Slot Table을 순회해야 합니다. 내부
remember가 캐시된 값을 반환하더라도, Group 마커 비교와 Slot Table 커서 이동 비용은 매번 발생합니다.

여기서 Slot Table은 또 뭐죠..?

Compose 컴파일러가 Composable 함수를 컴파일할때, 함수 내부 모든 상태 및 컴포지션 정보를 저장하고자 사용하는 선형 배열 기반 자료구조입니다.

이 Slot Table에 들어가는 정보는 아래와 같습니다.

- Group: @Composable 함수 호출 단위. 트리 구조를 선형 배열에 평탄화하여 저장
- Slot: Group 내부의 remember, mutableStateOf 등이 저장되는 칸

이 슬롯 테이블을 통해 상태를 관리하게 됨에 따라, 부모 컴포저블이 Recompose될때, Compose 런타임은 자식 컴포넌트의 슬롯 테이블 조회를 통해 자식 컴포넌트들 간 Recompose 범위를 판단하고, 함수 본체를 실행하지 않고 스킵할 수 있게 됩니다.

Slot Table 방식의 구조적 한계

이는 분명 함수 실행을 스킵해줄 수 있다는 성능상 이점이 있지만, Slot Table의 관리에 여전히 오버헤드는 존재합니다.

비용 발생 지점

1. 슬롯 할당/조회 오버헤드
   Re-compose가 발생할 때마다, Compose 런타임은 슬롯을 커서로 순회하며 Read 연산을 수행하며, 파라미터로 들어온 값과 슬롯에 저장된 값이 다를 경우, 새 값으로 업데이트합니다.
2. Gap Buffer 관리
   슬롯 테이블에는 새로운 컴포저블이 나타날 자리를 미리 비워두어, 삽입 시 기존 데이터를 일일이 밀어내 O(n)의 비용이 발생하지 않도록, 미리 Gap을 확보해놓습니다.

이 Gap은 현재 작업 중인 위치인 Cursor에 맞춰 계속 이동되며, 이로 인해 연속적인 삽입과 삭제 발생 시, 메모리 재할당이나 데이터 대량 복사 빈도를 획기적으로 줄여줍니다. 하지만, 여전히 gap을 새로운 위치로 이동시키는 과정에서 데이터의 복사 비용이 발생합니다.

2. Modifier.Node

튜닝 끝은 순정…

Modifier.Node는 Slot Table 구조로 인한 오버헤드를 해결하기 위해 Compose 1.3에서 도입된 composed modifier의 대체제이며, Slot Table 대신, 일반 Kotlin 클래스 내부 속성으로 상태를 저장합니다.

Slot Table 자료구조를 사용하여 각 Composable의 생명주기와 별개의 생명주기를 유지했던 Composed Modifier과 달리 Modifier.Node는 힙 메모리에 상주함으로써, 컴포저블과 다른 생명주기를 갖습니다.

이러한 구조로 인해, Modifier.Node는 담당하는 UI 요소(LayoutNode)가 직접 참조하는 방식으로 리컴포지션이 발생해도, 객체를 새로 만들지 않고, 노드의 프로퍼티만 업데이트합니다.

즉 힙 메모리 점유율을 UI 데이터 저장에 할애하는 대신, CPU 연산과 리컴포지션 오버헤드를 아끼는 트레이드 오프를 갖습니다.

각 Node는 아래 생명주기를 갖습니다.

- Node 생성 → onAttach() : Layout Tree에 부착됨
- 파라미터 변경 시 → update() : Element가 새 값을 전달
- Node 제거 → onDetach() : Layout Tree에서 분리됨

2.1 ModifierNodeElement

Node를 만들고 업데이트하는 “공장”

Modifie.chain의 역할을 대체하기 위해선 ModifierNodeElement가 중개자로서, Modifier.Node를 Modifier 체인에 연결해줘야 합니다.

// ModifierNodeElement: Node를 생성하고 업데이트하는 역할
data class CustomButtonElement(
    val transitionType: TransitionType,
    val isDisabled: Boolean,
    val action: () -> Unit,
    // ...
) : ModifierNodeElement<CustomButtonModifierNode>() {

    // Node를 처음 만들 때 호출됨
    override fun create() = CustomButtonModifierNode(
        transitionType = transitionType,
        isDisabled = isDisabled,
        action = action,
    )

    // 파라미터가 바뀌었을 때 기존 Node를 업데이트
    override fun update(node: CustomButtonModifierNode) {
        node.transitionType = transitionType
        node.isDisabled = isDisabled
        node.action = action
    }
}

Kotlin의 data class는 기본적으로 참조 비교를 수행하는 일반 클래스와 달리 객체의 데이터를 비교하는 equals 메서드를 자동으로 생성합니다. 이 equals 메서드를 활용하여 Compose 런타임은 이전 Element와 새 Element 간의 대조를 수행하며,

- 같으면 update() 메서드를 스킵
- 다르면, update(existingNode)를 호출하여, Node의 필드 갱신

을 수행합니다.

앞서 설명한 ComposedModifier가 lambda를 감싸고 있어 equals()가 항상 false였던 것과 대조적으로, ModifierNodeElement는 data class의 구조적 동등성(structural equality)을 활용하여 불필요한 업데이트를 건너뛸 수 있습니다.

2.2 LayoutModifierNode

RenderNode 기반 GPU 가속 변환

Compose의 렌더링은 3단계 파이프라인를 거칩니다.

앞 단계가 실행되면, 뒤 단계는 무조건 실행됩니다.

LayoutModifierNode는 Layout 단계에서 자식의 측정과 배치를 제어합니다. 여기서 핵심은 placeWithLayer()입니다. 이 메서드로 자식을 배치하면 RenderNode 기반의 그래픽 레이어가 생성됩니다.

class CustomButtonNode : Modifier.Node(), LayoutModifierNode {
    val scale = Animatable(1f)
    val backgroundAlpha = Animatable(0f)

    override fun MeasureScope.measure(
        measurable: Measurable,
        constraints: Constraints,
    ): MeasureResult {
        val placeable = measurable.measure(constraints)
        return layout(placeable.width, placeable.height) {
            placeable.placeWithLayer(0, 0) {
                // 이 람다 내부의 값 변경 → Layer invalidation만 발생
                // Composition, Layout 단계를 완전히 건너뜀
                scaleX = this@CustomButtonNode.scale.value
                scaleY = this@CustomButtonNode.scale.value
                alpha = 1f - this@CustomButtonNode.backgroundAlpha.value
                transformOrigin = TransformOrigin.Center
            }
        }
    }
}

RenderNode는 Android의 하드웨어 가속 렌더링 시스템의 핵심 요소로, 자식 콘텐츠를 Display List로 캐싱합니다. placeWithLayer 람다 내에서 scaleX, alpha, rotationX 등의 속성이 변경되면, 캐싱된 콘텐츠를 다시 그리지 않고 GPU에서 변환 속성만 갱신합니다. 이는 Compose가 제공하는 .graphicsLayer {} 수정자와 동일한 내부 메커니즘입니다.

2.3 DrawModifierNode

커스텀 드로잉

Draw 단계에서 커스텀 드로잉 로직을 직접 구현할 수 있는 인터페이스입니다. LayoutModifierNode의 placeWithLayer가 기존 콘텐츠에 변환을 적용하는 것이라면, DrawModifierNode는 새로운 시각 요소를 직접 그리는 역할입니다.

class CustomButtonNode : Modifier.Node(), DrawModifierNode {
    val backgroundAlpha = Animatable(0f)

    override fun ContentDrawScope.draw() {
        // 배경 라운드 렉트 그리기 (transform 전 원본 크기에 그려짐)
        val bgAlpha = backgroundAlpha.value
        if (bgAlpha > 0f) {
            drawRoundRect(
                color = Gray.copy(alpha = bgAlpha),
                cornerRadius = CornerRadius(8.dp.toPx()),
            )
        }
        drawContent()  // 자식 콘텐츠 그리기
    }
}

주의할 점은, scale/alpha/rotation과 같은 변환은 DrawModifierNode가 아닌 LayoutModifierNode의 placeWithLayer()로 처리해야 한다는 것입니다. DrawModifierNode의 draw() 내에서 Canvas API로 변환을 직접 구현하면 saveLayer 등의 비용이 발생하여 RenderNode의 Display List 캐싱 이점을 받을 수 없습니다. 이 부분은 7장에서 자세히 다루겠습니다.

2.4 LayoutAwareModifierNode

크기 변화 감지

class CustomButtonModifierNode : Modifier.Node(), LayoutAwareModifierNode {
    var componentSize = IntSize.Zero

    override fun onRemeasured(size: IntSize) {
        // Layout 단계에서 크기가 결정되면 자동 호출됨
        componentSize = size
    }
}

UI 요소의 크기가 변경되었을 때 호출하는 콜백을 정의하기 위해선, 기존에는 .onSizeChanged 수정자를 사용했습니다. LayoutAwareModifierNode는 Node의 인터페이스 메서드로 Layout 시스템이 직접 호출하며, 별도의 modifier 노드를 체인에 추가하지 않습니다.

2.5 DelegatingNode + SuspendingPointerInputModifierNode

SuspendingPointerInputModifierNode는 Compose에서 제공하며 Modifier.Node를 상속하는 터치 감지(press/release)를 처리하는 독립적인 클래스입니다.

class CustomButtonNode(/*...*/) :
    DelegatingNode(),          // 다른 Node를 위임할 수 있게 함
    LayoutModifierNode,        // placeWithLayer() 직접 구현
    DrawModifierNode,          // draw() 직접 구현
    LayoutAwareModifierNode    // onRemeasured() 직접 구현
{
    // 터치 처리를 담당하는 서브 Node를 생성하고 "위임 등록"
    val pointerInputNode = delegate(
        SuspendingPointerInputModifierNode {
            detectTapGestures(
                onPress = { offset ->
                    // 프레스 애니메이션 시작
                },
                onTap = { action() }
            )
        }
    )
}

DelegatingNode를 상속하면 delegate()를 통해 서브 노드를 등록할 수 있습니다. 이를 통해 LayoutModifierNode, DrawModifierNode, LayoutAwareModifierNode, SuspendingPointerInputModifierNode의 기능을 단일 노드에 통합할 수 있습니다. 기존에는 이들이 각각 별도의 modifier 노드로 체인에 추가되어 4~5개의 노드가 존재했지만, DelegatingNode를 통해 1개로 줄어듭니다.

3. CustomButton 성능 최적화하기

제가 현재 담당하고 있는 프로젝트에 가장 많이 사용되고 있는 버튼 공용 컴포넌트에 Modifier.Node API를 적용해보기로 했습니다.

기존 CustomButton의 구현

object CustomButtonLegacy {
    @Composable
    operator fun invoke(
        modifier: Modifier = Modifier,
        action: () -> Unit,
        transitionType: TransitionType = TransitionType.Shrink,
        isDisabled: Boolean = false,
        content: @Composable () -> Unit
    ) {
        // ── Slot Table에 6개의 슬롯이 할당되는 구간 ──
        val scale = remember { Animatable(1f) }             // Slot 1
        val backgroundAlpha = remember { Animatable(0f) }   // Slot 2
        val tiltX = remember { Animatable(0f) }             // Slot 3
        val tiltY = remember { Animatable(0f) }             // Slot 4
        val coroutineScope = rememberCoroutineScope()        // Slot 5
        var componentSize by remember { mutableStateOf(IntSize.Zero) } // Slot 6

        Row(
            modifier = modifier
                .background(                                            // ⚠ Composition 스코프에서 State 읽기
                    Gray.copy(alpha = backgroundAlpha.value), ...
                )
                .onSizeChanged { componentSize = it }                   // 별도 modifier 노드
                .graphicsLayer {                                        // 별도 modifier 노드
                    alpha = 1f - backgroundAlpha.value
                    scaleX = scale.value
                    scaleY = scale.value
                    rotationX = tiltX.value
                    rotationY = tiltY.value
                }
                .pointerInput(isDisabled) {                             // 별도 modifier 노드
                    detectTapGestures(
                        onPress = { offset ->
                            coroutineScope.launch {
                                scale.animateTo(0.97f, tween(100))
                            }
                            // ... 나머지 애니메이션
                            tryAwaitRelease()
                            coroutineScope.launch {
                                scale.animateTo(1f, tween(400))
                            }
                            // ...
                        },
                        onTap = { action() }
                    )
                },
        ) { content() }
    }
}

버튼 탭에 대한 트랜지션은 크게 3가지 요인으로 구성됩니다.
- 투명도를 다루는 Alpha
- 버튼의 크기가 변경되는 Scale
- 버튼을 감싸는 영역의 배경색상인 Background

여기서 주목해야 할 것은 State를 어디서 읽느냐에 따라 렌더링 파이프라인의 진입 지점이 달라진다는 점입니다.

Scale/Alpha 애니메이션은 .graphicsLayer {} 람다 내부에서 State를 읽습니다. .graphicsLayer {} 람다는 내부적으로 RenderNode의 속성을 설정하는 Draw 단계 스코프에서 실행되기 때문에, Recomposition이 트리거되지 않습니다.

하지만 .background(Gray.copy(alpha = backgroundAlpha.value)) 호출은 Composable 함수 본문, 즉 Composition 스코프에서 State를 읽기 때문에 매 애니메이션 프레임마다 Recomposition이 트리거됩니다.

오버헤드 요약

remember * 4 + rememberCoroutineScope + mutableStateOf
Slot Table에 6개 슬롯 할당, Recomposition마다 커서 순회 비용 발생

.background(alpha = backgroundAlpha.value)
Composition 스코프에서 State 읽기 → 매 프레임 Recomposition 트리거.

.onSizeChanged, .graphicsLayer, .pointerInput
각각 별도의 modifier 노드 → 체인 길이 증가

위 분석을 바탕으로, 4개의 modifier 노드를 단일 Modifier.Node로 통합했습니다.

object CustomButton {
    @Composable
    operator fun invoke(
        modifier: Modifier = Modifier,
        action: () -> Unit,
        transitionType: TransitionType = TransitionType.Shrink,
        isDisabled: Boolean = false,
        content: @Composable () -> Unit
    ) {
        Row(
            // Modifier 체인에 Node Element 하나만 추가
            modifier = modifier
                .then(CustomButtonElement(transitionType, isDisabled, action))
                .then(
                    if (transitionType == TransitionType.ShrinkWithGrayBackground)
                        Modifier.padding(4.dp)
                    else Modifier
                ),
            // ...
        ) { content() }
    }
}

기존 SlotTable 순회 오버헤드를 트리거하던 remember과 mutableStateOf의 경우, 아래 Node 클래스 내부에서 일반 클래스 필드로 관리됩니다.

private class CustomButtonNode(
    var transitionType: TransitionType,
    var isDisabled: Boolean,
    var action: () -> Unit,
) : DelegatingNode(),
    LayoutModifierNode,    // placeWithLayer() - RenderNode 기반 GPU 변환
    DrawModifierNode,      // draw() - ShrinkWithGrayBackground 배경 전용
    LayoutAwareModifierNode // onRemeasured() - 크기 추적
{
    // 애니메이션 상태: Node 필드에 직접 저장 (Slot Table 미사용)
    private val scale = Animatable(1f)
    private val backgroundAlpha = Animatable(0f)
    private val tiltX = Animatable(0f)
    private val tiltY = Animatable(0f)
    private var componentSize = IntSize.Zero

    // 터치 처리: SuspendingPointerInputModifierNode로 위임
    private val pointerInputNode = delegate(
        SuspendingPointerInputModifierNode {
            detectTapGestures(
                onPress = { offset ->
                    animatePress(offset)
                    tryAwaitRelease()
                    animateRelease()
                },
                onTap = { action() }
            )
        }
    )

    // LayoutAwareModifierNode: 크기 추적
    override fun onRemeasured(size: IntSize) {
        if (transitionType == TransitionType.ShrinkWithTilt) {
            componentSize = size
        }
    }

    // LayoutModifierNode: RenderNode 기반 GPU 가속 변환
    // placeWithLayer 람다 내 값 변경 → Layer invalidation만 발생
    override fun MeasureScope.measure(
        measurable: Measurable,
        constraints: Constraints,
    ): MeasureResult {
        val placeable = measurable.measure(constraints)
        return layout(placeable.width, placeable.height) {
            placeable.placeWithLayer(0, 0) {
                scaleX = this@CustomButtonNode.scale.value
                scaleY = this@CustomButtonNode.scale.value
                alpha = 1f - this@CustomButtonNode.backgroundAlpha.value
                transformOrigin = TransformOrigin.Center

                if (this@CustomButtonNode.transitionType == TransitionType.ShrinkWithTilt) {
                    rotationX = this@CustomButtonNode.tiltX.value
                    rotationY = this@CustomButtonNode.tiltY.value
                }
            }
        }
    }

    // DrawModifierNode: ShrinkWithGrayBackground 배경 전용
    override fun ContentDrawScope.draw() {
        if (transitionType == TransitionType.ShrinkWithGrayBackground) {
            val bgAlpha = backgroundAlpha.value
            if (bgAlpha > 0f) {
                drawRoundRect(
                    color = Gray.copy(alpha = bgAlpha),
                    cornerRadius = CornerRadius(8.dp.toPx()),
                )
            }
        }
        drawContent()
    }
}

Modifier.Node를 사용하면서 진행한 변경점은 아래와 같습니다.

1. Slot Table 슬롯 수
   전: 6개
   후: 0개
2. 애니메이션 중 Recompositon
   전: background() 수정자로 인한 매 프레임 발생
   후: 발생하지 않으며, Draw invalidation만 수행
3. 변환 메커니즘
   전: .graphicsLayer {} (RenderNode)
   후: placeWithLayer {} (RenderNode)
4. modifier 체인 노드 수 (버튼당)
   전: 4~5개
   후: 1개 (DelegatingNode)

4. 성능 검증 -UIAutomator를 활용한 프레임 성능 측정

Android의 UIAutomator 프레임워크와 dumpsys gfxinfo 시스템 명령을 사용하여 Modifier.Node로의 전환이 성능상 이점이 있는지 검증해보고자 했습니다.

1. UIAutomator
Android에서 제공하는 UI 자동화 테스트 프레임워크입니다. Espresso와 달리 앱 내부의 Compose/View 계층에 대한 직접적인 접근이 아닌, 시스템 수준에서 사용자 상호작용을 시뮬레이션합니다. 이는 성능 테스트에 있어 중요한 차이점인데, 테스트 코드 자체가 앱의 렌더링 파이프라인에 간섭하지 않기 때문에 보다 정확한 프레임 성능을 측정할 수 있습니다.

2. dumpsys gfxinfo
Android 시스템이 프로세스별로 수집하는 그래픽 렌더링 통계를 조회하는 명령입니다.

4.1 테스트 환경 설계: Compose 캐시 격리

정확한 비교를 위해 가장 신경 쓴 부분은 Compose 런타임 캐시의 격리입니다. 만약 CustomButtonLegacy와 CustomButton을 탭으로 전환하는 구조를 사용하면, 첫 번째 탭에서 생성된 Composition 캐시(Slot Table, 메모리 풀 등)가 두 번째 탭의 측정에 영향을 줄 수 있습니다.

이를 방지하기 위해 독립된 하위 화면 구조를 채택했습니다.

앱 실행 → “CustomButtonLegacy” 하위 화면 진입 → 10회 스크롤 측정
→ pressBack() → 메뉴 복귀 (Compose 트리 완전 해제) → “CustomButton” 하위 화면 진입 → 10회 스크롤 측정 → 결과 비교 출력

4.2 테스트 케이스 1:

스크롤 성능 — 다수 버튼이 동시에 존재하는 환경

@Test
fun scrollPerformance_customButton_vs_customButtonLegacy() = uiAutomator {
    // Legacy 화면 진입 → 10회 반복 (gfxinfo reset → 아래 스크롤 → 위 스크롤 → gfxinfo 수집)
    // → pressBack() → Node 화면 진입 → 동일 10회 반복
}

CustomButtonLegacy는 버튼 1개당 6개의 Slot을 차지하므로, 60개 버튼이 동시에 렌더링되면 360개의 슬롯이 Slot Table에 할당됩니다. 또한 버튼당 4~5개의 별도 modifier 노드가 존재하여, 60개 버튼 기준 240~300개의 modifier 노드가 체인에 존재합니다. 컴포넌트 수가 많아질수록 이러한 오버헤드가 증폭되는지를 확인하고자 했습니다.

4.3 테스트 케이스 2:

LongClick Transition — 단일 버튼의 애니메이션 프레임 분석

@Test
fun longClickTransition_customButton_vs_customButtonLegacy() = uiAutomator {
    // Single Legacy 화면 진입 → 20회 반복 (gfxinfo reset → longClick → release 대기 → gfxinfo 수집)
    // → pressBack() → Single Node 화면 진입 → 동일 20회 반복
}

스크롤 테스트가 다수 버튼의 존재 비용을 측정한다면, 이 테스트는 단일 버튼의 애니메이션 실행 비용을 격리하여 측정합니다. 화면에 버튼 1개만 배치하여 다른 컴포넌트의 렌더링 비용을 완전히 제거한 후 테스트하고자 했습니다.

longClick은 device.swipe(cx, cy, cx, cy, steps)로 구현했습니다. 동일 좌표로의 swipe는 UIAutomator에서 press → hold → release 사이클과
동일하게 동작하며, steps 값으로 유지 시간을 제어합니다(600ms).

Press 시작 → scale 축소 애니메이션 (100ms) → 유지 (약 500ms) → Release → scale 복원 애니메이션 (400ms) → Release 애니메이션 완료 대기 (500ms) → gfxinfo 수집

5. 성능 테스트 결과

03-01 18:10:21.329 [LongClickPerfComparison] ════════════════════════════════════════
03-01 18:10:21.329 [LongClickPerfComparison]  HMButton (Modifier.Node) — LongClick Transition
03-01 18:10:21.329 [LongClickPerfComparison] ════════════════════════════════════════
03-01 18:10:21.329 [LongClickPerfComparison]  #1  Total: 60, Janky: 2, P99: 22ms
03-01 18:10:21.329 [LongClickPerfComparison]  #2  Total: 60, Janky: 2, P99: 11ms
03-01 18:10:21.329 [LongClickPerfComparison]  #3  Total: 60, Janky: 1, P99: 15ms
03-01 18:10:21.329 [LongClickPerfComparison]  #4  Total: 60, Janky: 2, P99: 10ms
03-01 18:10:21.329 [LongClickPerfComparison]  #5  Total: 61, Janky: 1, P99: 14ms
03-01 18:10:21.330 [LongClickPerfComparison]  #6  Total: 60, Janky: 2, P99: 11ms
03-01 18:10:21.330 [LongClickPerfComparison]  #7  Total: 60, Janky: 2, P99: 12ms
03-01 18:10:21.330 [LongClickPerfComparison]  #8  Total: 59, Janky: 1, P99: 15ms
03-01 18:10:21.330 [LongClickPerfComparison]  #9  Total: 61, Janky: 2, P99: 17ms
03-01 18:10:21.330 [LongClickPerfComparison]  #10  Total: 60, Janky: 2, P99: 15ms
03-01 18:10:21.330 [LongClickPerfComparison]  #11  Total: 61, Janky: 1, P99: 12ms
03-01 18:10:21.330 [LongClickPerfComparison]  #12  Total: 60, Janky: 2, P99: 10ms
03-01 18:10:21.330 [LongClickPerfComparison]  #13  Total: 60, Janky: 2, P99: 10ms
03-01 18:10:21.330 [LongClickPerfComparison]  #14  Total: 60, Janky: 1, P99: 9ms
03-01 18:10:21.330 [LongClickPerfComparison]  #15  Total: 60, Janky: 2, P99: 8ms
03-01 18:10:21.330 [LongClickPerfComparison]  #16  Total: 60, Janky: 1, P99: 11ms
03-01 18:10:21.330 [LongClickPerfComparison]  #17  Total: 60, Janky: 2, P99: 18ms
03-01 18:10:21.330 [LongClickPerfComparison]  #18  Total: 60, Janky: 2, P99: 12ms
03-01 18:10:21.330 [LongClickPerfComparison]  #19  Total: 60, Janky: 2, P99: 18ms
03-01 18:10:21.330 [LongClickPerfComparison]  #20  Total: 61, Janky: 2, P99: 14ms
03-01 18:10:21.331 [LongClickPerfComparison]  AVG Total: 60.15, AVG Janky: 1.70, AVG P99: 13.20ms
03-01 18:10:21.331 [LongClickPerfComparison] ════════════════════════════════════════
03-01 18:10:21.331 [LongClickPerfComparison]  HMButtonLegacy (Standard Compose) — LongClick Transition
03-01 18:10:21.331 [LongClickPerfComparison] ════════════════════════════════════════
03-01 18:10:21.331 [LongClickPerfComparison]  #1  Total: 60, Janky: 2, P99: 26ms
03-01 18:10:21.331 [LongClickPerfComparison]  #2  Total: 59, Janky: 2, P99: 17ms
03-01 18:10:21.331 [LongClickPerfComparison]  #3  Total: 60, Janky: 2, P99: 16ms
03-01 18:10:21.331 [LongClickPerfComparison]  #4  Total: 60, Janky: 2, P99: 17ms
03-01 18:10:21.331 [LongClickPerfComparison]  #5  Total: 60, Janky: 2, P99: 16ms
03-01 18:10:21.332 [LongClickPerfComparison]  #6  Total: 60, Janky: 2, P99: 12ms
03-01 18:10:21.332 [LongClickPerfComparison]  #7  Total: 60, Janky: 2, P99: 11ms
03-01 18:10:21.332 [LongClickPerfComparison]  #8  Total: 60, Janky: 2, P99: 12ms
03-01 18:10:21.332 [LongClickPerfComparison]  #9  Total: 59, Janky: 2, P99: 15ms
03-01 18:10:21.332 [LongClickPerfComparison]  #10  Total: 60, Janky: 2, P99: 12ms
03-01 18:10:21.332 [LongClickPerfComparison]  #11  Total: 60, Janky: 2, P99: 16ms
03-01 18:10:21.332 [LongClickPerfComparison]  #12  Total: 60, Janky: 2, P99: 14ms
03-01 18:10:21.332 [LongClickPerfComparison]  #13  Total: 61, Janky: 2, P99: 14ms
03-01 18:10:21.332 [LongClickPerfComparison]  #14  Total: 60, Janky: 2, P99: 14ms
03-01 18:10:21.332 [LongClickPerfComparison]  #15  Total: 60, Janky: 2, P99: 18ms
03-01 18:10:21.332 [LongClickPerfComparison]  #16  Total: 61, Janky: 2, P99: 12ms
03-01 18:10:21.332 [LongClickPerfComparison]  #17  Total: 60, Janky: 2, P99: 14ms
03-01 18:10:21.332 [LongClickPerfComparison]  #18  Total: 61, Janky: 2, P99: 16ms
03-01 18:10:21.332 [LongClickPerfComparison]  #19  Total: 61, Janky: 2, P99: 17ms
03-01 18:10:21.332 [LongClickPerfComparison]  #20  Total: 60, Janky: 2, P99: 15ms
03-01 18:10:21.333 [LongClickPerfComparison]  AVG Total: 60.10, AVG Janky: 2.00, AVG P99: 15.20ms
03-01 18:10:21.333 [LongClickPerfComparison] ════════════════════════════════════════
03-01 18:10:21.333 [LongClickPerfComparison]  COMPARISON
03-01 18:10:21.333 [LongClickPerfComparison] ════════════════════════════════════════
03-01 18:10:21.333 [LongClickPerfComparison]  Total frames — Node: 60.15, Legacy: 60.10
03-01 18:10:21.333 [LongClickPerfComparison]  Janky frames improvement: 15.0%
03-01 18:10:21.333 [LongClickPerfComparison]  P99 frame time improvement: 13.2%
03-01 18:10:21.333 [LongClickPerfComparison] ════════════════════════════════════════

03-01 19:41:08.200 [ButtonPerfComparison] ════════════════════════════════════════
03-01 19:41:08.200 [ButtonPerfComparison]  HMButton (Modifier.Node) Results
03-01 19:41:08.200 [ButtonPerfComparison] ════════════════════════════════════════
03-01 19:41:08.200 [ButtonPerfComparison]  #1  Total: 86, Janky: 7, P99: 16ms
03-01 19:41:08.200 [ButtonPerfComparison]  #2  Total: 101, Janky: 4, P99: 8ms
03-01 19:41:08.200 [ButtonPerfComparison]  #3  Total: 102, Janky: 5, P99: 19ms
03-01 19:41:08.200 [ButtonPerfComparison]  #4  Total: 100, Janky: 5, P99: 16ms
03-01 19:41:08.201 [ButtonPerfComparison]  #5  Total: 101, Janky: 3, P99: 9ms
03-01 19:41:08.201 [ButtonPerfComparison]  #6  Total: 101, Janky: 6, P99: 9ms
03-01 19:41:08.201 [ButtonPerfComparison]  #7  Total: 102, Janky: 4, P99: 10ms
03-01 19:41:08.201 [ButtonPerfComparison]  #8  Total: 103, Janky: 2, P99: 9ms
03-01 19:41:08.201 [ButtonPerfComparison]  #9  Total: 101, Janky: 3, P99: 10ms
03-01 19:41:08.201 [ButtonPerfComparison]  #10  Total: 102, Janky: 2, P99: 8ms
03-01 19:41:08.203 [ButtonPerfComparison]  AVG Total: 99.90, AVG Janky: 4.10, AVG P99: 11.40ms
03-01 19:41:08.203 [ButtonPerfComparison] ════════════════════════════════════════
03-01 19:41:08.203 [ButtonPerfComparison]  HMButtonLegacy (Standard Compose) Results
03-01 19:41:08.203 [ButtonPerfComparison] ════════════════════════════════════════
03-01 19:41:08.203 [ButtonPerfComparison]  #1  Total: 84, Janky: 10, P99: 24ms
03-01 19:41:08.203 [ButtonPerfComparison]  #2  Total: 105, Janky: 9, P99: 12ms
03-01 19:41:08.203 [ButtonPerfComparison]  #3  Total: 101, Janky: 8, P99: 14ms
03-01 19:41:08.203 [ButtonPerfComparison]  #4  Total: 103, Janky: 11, P99: 12ms
03-01 19:41:08.203 [ButtonPerfComparison]  #5  Total: 104, Janky: 9, P99: 12ms
03-01 19:41:08.203 [ButtonPerfComparison]  #6  Total: 102, Janky: 9, P99: 18ms
03-01 19:41:08.204 [ButtonPerfComparison]  #7  Total: 104, Janky: 8, P99: 11ms
03-01 19:41:08.204 [ButtonPerfComparison]  #8  Total: 102, Janky: 7, P99: 9ms
03-01 19:41:08.204 [ButtonPerfComparison]  #9  Total: 103, Janky: 7, P99: 10ms
03-01 19:41:08.204 [ButtonPerfComparison]  #10  Total: 103, Janky: 5, P99: 11ms
03-01 19:41:08.204 [ButtonPerfComparison]  AVG Total: 101.10, AVG Janky: 8.30, AVG P99: 13.30ms
03-01 19:41:08.204 [ButtonPerfComparison] ════════════════════════════════════════
03-01 19:41:08.204 [ButtonPerfComparison]  COMPARISON
03-01 19:41:08.205 [ButtonPerfComparison] ════════════════════════════════════════
03-01 19:41:08.205 [ButtonPerfComparison]  Janky frames improvement: 50.6%
03-01 19:41:08.205 [ButtonPerfComparison]  P99 frame time improvement: 14.3%
03-01 19:41:08.205 [ButtonPerfComparison] ════════════════════════════════════════

1. 단일 버튼 테스트
   Janky 개선율: 15.0%
   P99 개선율: 13.2%
2. 60개 버튼 테스트
   Janky 개선율: 50.6%
   P99 개선율: 14.3%

화면에 존재하는 컴포넌트 수가 많아질수록 Modifier.Node의 이점이 극대화되는 것을 확인할 수 있습니다.

단일 버튼에서도 15%의 Janky 개선이 발생한 이유는 .background(alpha = backgroundAlpha.value)가 매 애니메이션 프레임마다 Recomposition을 트리거하여, 6개의 Slot Table 슬롯에 대한 커서 순회와 Group 마커 비교가 매번 발생했기 때문입니다.

60개 버튼 스크롤에서 Janky 개선율이 50.6%로 크게 증가한 이유는 주로 초기 Composition 비용과 GC 압박에 있습니다. CustomButtonLegacy 60개가 동시에 Compose되면 360개의 Slot Table 슬롯 + 240~300개의 modifier 노드 인스턴스가 생성됩니다. 이 객체들이 힙 메모리를 점유하면서 GC 발생 확률이 높아지고, GC pause는 스크롤 중 예측 불가능한 Jank 프레임을 유발합니다.

6. 마무리

Modifier.Node API는 Composed Modifier가 암묵적으로 수행하던 Slot Table 할당, 커서 순회, Gap Buffer 관리를 완전히 우회합니다. 그 대가로 ModifierNodeElement, DelegatingNode, DrawModifierNode 등 여러 클래스를 직접 구현해야 하는 코드 복잡도가 발생합니다.

따라서 모든 Modifier를 Node로 마이그레이션하는 것은 권장하지 않습니다. 최적화 대상을 선정할 때는 다음 기준을 고려하는 것이 바람직합니다.

- 프레임 단위로 상태가 변경되는 컴포넌트 (애니메이션이 포함된 버튼, 드래그 핸들 등)
- 리스트나 그리드처럼 다수가 동시에 존재하는 컴포넌트
- 여러 Composed Modifier가 체이닝된 컴포넌트 (단일 Node로 통합할 수 있는 경우)

이 세 조건 중 두 가지 이상에 해당한다면, Modifier.Node 마이그레이션을 통해 유의미한 성능 개선을 기대할 수 있습니다. 본 글에서 다룬 CustomButton은 세 조건을 모두 충족하는 케이스였으며, 실제 측정 결과도 이를 뒷받침했습니다.

7. …인줄 알았으나,,, 놓친 포인트

saveLayer vs RenderNode

위 테스트는 .background() 수정자가 사용되는 ShrinkWithGrayBackground로 진행되었습니다. 이 TransitionType에서는 Legacy 버전이 .background()수정자로 인해 매 프레임 Recomposition이 발생하므로, Node 버전의 성능 이점이 명확했습니다.

그런데 .background() 수정자를 사용하지 않는 Shrink로 테스트를 진행하면 어떨까요? Shrink 타입은 Scale과 Alpha만 변경하며, 이 값들은 Legacy에서도 .graphicsLayer {} 람다 내에서 읽히므로 Recomposition이 발생하지 않습니다.

03-01 19:40:42.560: [LongClickPerfComparison] ════════════════════════════════════════
03-01 19:40:42.560: [LongClickPerfComparison]  COMPARISON
03-01 19:40:42.560: [LongClickPerfComparison] ════════════════════════════════════════
03-01 19:40:42.561: [LongClickPerfComparison]  Total frames — Node: 60.05, Legacy: 60.25
03-01 19:40:42.561: [LongClickPerfComparison]  Janky frames improvement: -12.9% ← Node 버전이 오히려 느림
03-01 19:40:42.561: [LongClickPerfComparison]  P99 frame time improvement: -5.6%
03-01 19:40:42.561: [LongClickPerfComparison] ════════════════════════════════════════

Recomposition이 발생하지 않는 조건에서는, Modifier.Node 버전이 오히려 더 느렸습니다,,,!

7.1 원인 분석: Canvas saveLayer의 비용

초기 CustomButtonNode 구현에서는 scale, alpha, rotation 변환을 DrawModifierNode의 draw() 내에서 Canvas API로 직접 처리했습니다.

// 초기 구현 (문제 있는 코드)
override fun ContentDrawScope.draw() {
  val nativeCanvas = drawContext.canvas.nativeCanvas

  // alpha 적용을 위한 saveLayer — 매 프레임 오프스크린 버퍼 할당
  layerPaint.alpha = ((1f - bgAlpha) * 255).toInt()
  nativeCanvas.saveLayer(0f, 0f, size.width, size.height, layerPaint)

  // scale 적용
  nativeCanvas.scale(currentScale, currentScale, size.width / 2, size.height / 2)

  drawContent()  // 자식 콘텐츠를 매 프레임 다시 그림
  nativeCanvas.restore()
}

saveLayer는 오프스크린 버퍼(offscreen buffer)를 할당하고, 그 위에 콘텐츠를 처음부터 다시 그린 뒤, 결과를 메인 캔버스에 합성합니다. 이 과정이 매 애니메이션 프레임마다 반복됩니다.

반면, Legacy의 .graphicsLayer {} 수정자는 내부적으로 RenderNode를 사용합니다.

ShrinkWithGrayBackground 테스트에서 Node 버전이 빨랐던 이유는 Legacy의 .background()가 매 프레임 Recomposition을 유발하는 오버헤드가 saveLayer의 비용보다 컸기 때문이었습니다. 하지만 Shrink 타입에서는 Recomposition이 발생하지 않으므로, Legacy의 RenderNode 대 Node의 saveLayer 순수 비교가 되었고, RenderNode가 더 효율적이었던 것입니다

7.2 수정: LayoutModifierNode.placeWithLayer()

때문에, 변환 로직을 DrawModifierNode의 Canvas API에서 LayoutModifierNode의 placeWithLayer()로 이전했습니다.

// 수정 후: RenderNode 기반 GPU 가속 변환
override fun MeasureScope.measure(
    measurable: Measurable,
    constraints: Constraints,
): MeasureResult {
    val placeable = measurable.measure(constraints)
    return layout(placeable.width, placeable.height) {
        placeable.placeWithLayer(0, 0) {
            scaleX = this@CustomButtonNode.scale.value
            scaleY = this@CustomButtonNode.scale.value
            alpha = 1f - this@CustomButtonNode.backgroundAlpha.value
            transformOrigin = TransformOrigin.Center

            if (this@CustomButtonNode.transitionType == TransitionType.ShrinkWithTilt) {
                rotationX = this@CustomButtonNode.tiltX.value
                rotationY = this@CustomButtonNode.tiltY.value
            }
        }
    }
}

// DrawModifierNode는 ShrinkWithGrayBackground 배경 드로잉 전용으로 축소
override fun ContentDrawScope.draw() {
    if (transitionType == TransitionType.ShrinkWithGrayBackground) {
        val bgAlpha = backgroundAlpha.value
        if (bgAlpha > 0f) {
            drawRoundRect(
                color = Gray.copy(alpha = bgAlpha),
                cornerRadius = CornerRadius(8.dp.toPx()),
            )
        }
    }
    drawContent()
}

placeWithLayer()는 Legacy의 .graphicsLayer {}와 동일한 RenderNode 기반 경로를 사용합니다. 콘텐츠를 Display List로 캐싱하고, 애니메이션 중에는 GPU에서 변환 속성만 갱신합니다. DrawModifierNode는 ShrinkWithGrayBackground 타입에서 배경 라운드 렉트를 그리는 용도로만 사용하도록 역할을 분리했습니다.

7.3 Shrink Transition 재테스트 결과

RenderNode 기반으로 수정 후, .background() 수정자가 사용되지 않는 TransitionType.Shrink로 다시 테스트를 진행했습니다.

03-01 20:32:34.086 [LongClickPerfComparison] ════════════════════════════════════════
03-01 20:32:34.086 [LongClickPerfComparison]  HMButton (Modifier.Node) — LongClick Transition
03-01 20:32:34.087 [LongClickPerfComparison] ════════════════════════════════════════
03-01 20:32:34.087 [LongClickPerfComparison]  #1  Total: 60, Janky: 1, P99: 8ms
03-01 20:32:34.087 [LongClickPerfComparison]  #2  Total: 60, Janky: 2, P99: 18ms
03-01 20:32:34.087 [LongClickPerfComparison]  #3  Total: 60, Janky: 2, P99: 12ms
03-01 20:32:34.087 [LongClickPerfComparison]  #4  Total: 60, Janky: 1, P99: 12ms
03-01 20:32:34.087 [LongClickPerfComparison]  #5  Total: 60, Janky: 2, P99: 12ms
03-01 20:32:34.087 [LongClickPerfComparison]  #6  Total: 61, Janky: 1, P99: 8ms
03-01 20:32:34.087 [LongClickPerfComparison]  #7  Total: 59, Janky: 2, P99: 14ms
03-01 20:32:34.088 [LongClickPerfComparison]  #8  Total: 60, Janky: 1, P99: 10ms
03-01 20:32:34.088 [LongClickPerfComparison]  #9  Total: 60, Janky: 2, P99: 17ms
03-01 20:32:34.088 [LongClickPerfComparison]  #10  Total: 60, Janky: 1, P99: 8ms
03-01 20:32:34.088 [LongClickPerfComparison]  #11  Total: 60, Janky: 2, P99: 17ms
03-01 20:32:34.088 [LongClickPerfComparison]  #12  Total: 60, Janky: 2, P99: 18ms
03-01 20:32:34.088 [LongClickPerfComparison]  #13  Total: 60, Janky: 2, P99: 16ms
03-01 20:32:34.088 [LongClickPerfComparison]  #14  Total: 60, Janky: 2, P99: 11ms
03-01 20:32:34.088 [LongClickPerfComparison]  #15  Total: 59, Janky: 1, P99: 13ms
03-01 20:32:34.088 [LongClickPerfComparison]  #16  Total: 60, Janky: 2, P99: 11ms
03-01 20:32:34.089 [LongClickPerfComparison]  #17  Total: 60, Janky: 1, P99: 8ms
03-01 20:32:34.089 [LongClickPerfComparison]  #18  Total: 60, Janky: 1, P99: 12ms
03-01 20:32:34.089 [LongClickPerfComparison]  #19  Total: 60, Janky: 2, P99: 12ms
03-01 20:32:34.089 [LongClickPerfComparison]  #20  Total: 61, Janky: 2, P99: 17ms
03-01 20:32:34.090 [LongClickPerfComparison]  AVG Total: 60.00, AVG Janky: 1.60, AVG P99: 12.70ms
03-01 20:32:34.090 [LongClickPerfComparison] ════════════════════════════════════════
03-01 20:32:34.090 [LongClickPerfComparison]  HMButtonLegacy (Standard Compose) — LongClick Transition
03-01 20:32:34.090 [LongClickPerfComparison] ════════════════════════════════════════
03-01 20:32:34.090 [LongClickPerfComparison]  #1  Total: 61, Janky: 2, P99: 17ms
03-01 20:32:34.090 [LongClickPerfComparison]  #2  Total: 60, Janky: 2, P99: 16ms
03-01 20:32:34.091 [LongClickPerfComparison]  #3  Total: 61, Janky: 1, P99: 15ms
03-01 20:32:34.091 [LongClickPerfComparison]  #4  Total: 59, Janky: 2, P99: 10ms
03-01 20:32:34.091 [LongClickPerfComparison]  #5  Total: 59, Janky: 2, P99: 14ms
03-01 20:32:34.091 [LongClickPerfComparison]  #6  Total: 61, Janky: 1, P99: 10ms
03-01 20:32:34.091 [LongClickPerfComparison]  #7  Total: 61, Janky: 1, P99: 12ms
03-01 20:32:34.091 [LongClickPerfComparison]  #8  Total: 60, Janky: 2, P99: 15ms
03-01 20:32:34.091 [LongClickPerfComparison]  #9  Total: 60, Janky: 2, P99: 8ms
03-01 20:32:34.091 [LongClickPerfComparison]  #10  Total: 59, Janky: 2, P99: 14ms
03-01 20:32:34.091 [LongClickPerfComparison]  #11  Total: 60, Janky: 2, P99: 18ms
03-01 20:32:34.091 [LongClickPerfComparison]  #12  Total: 60, Janky: 2, P99: 9ms
03-01 20:32:34.091 [LongClickPerfComparison]  #13  Total: 60, Janky: 1, P99: 11ms
03-01 20:32:34.092 [LongClickPerfComparison]  #14  Total: 60, Janky: 2, P99: 13ms
03-01 20:32:34.092 [LongClickPerfComparison]  #15  Total: 61, Janky: 1, P99: 12ms
03-01 20:32:34.092 [LongClickPerfComparison]  #16  Total: 60, Janky: 2, P99: 17ms
03-01 20:32:34.092 [LongClickPerfComparison]  #17  Total: 61, Janky: 2, P99: 13ms
03-01 20:32:34.092 [LongClickPerfComparison]  #18  Total: 60, Janky: 1, P99: 16ms
03-01 20:32:34.092 [LongClickPerfComparison]  #19  Total: 60, Janky: 2, P99: 17ms
03-01 20:32:34.092 [LongClickPerfComparison]  #20  Total: 61, Janky: 2, P99: 10ms
03-01 20:32:34.093 [LongClickPerfComparison]  AVG Total: 60.20, AVG Janky: 1.70, AVG P99: 13.35ms
03-01 20:32:34.093 [LongClickPerfComparison] ════════════════════════════════════════
03-01 20:32:34.093 [LongClickPerfComparison]  COMPARISON
03-01 20:32:34.093 [LongClickPerfComparison] ════════════════════════════════════════
03-01 20:32:34.093 [LongClickPerfComparison]  Total frames — Node: 60.00, Legacy: 60.20
03-01 20:32:34.093 [LongClickPerfComparison]  Janky frames improvement: 5.9%
03-01 20:32:34.093 [LongClickPerfComparison]  P99 frame time improvement: 4.9%
03-01 20:32:34.093 [LongClickPerfComparison] ════════════════════════════════════════
03-01 20:32:59.754 [ButtonPerfComparison] ════════════════════════════════════════
03-01 20:32:59.754 [ButtonPerfComparison]  HMButton (Modifier.Node) Results
03-01 20:32:59.754 [ButtonPerfComparison] ════════════════════════════════════════
03-01 20:32:59.754 [ButtonPerfComparison]  #1  Total: 87, Janky: 6, P99: 17ms
03-01 20:32:59.754 [ButtonPerfComparison]  #2  Total: 101, Janky: 5, P99: 10ms
03-01 20:32:59.754 [ButtonPerfComparison]  #3  Total: 103, Janky: 3, P99: 10ms
03-01 20:32:59.754 [ButtonPerfComparison]  #4  Total: 101, Janky: 4, P99: 11ms
03-01 20:32:59.754 [ButtonPerfComparison]  #5  Total: 102, Janky: 3, P99: 8ms
03-01 20:32:59.754 [ButtonPerfComparison]  #6  Total: 101, Janky: 5, P99: 9ms
03-01 20:32:59.754 [ButtonPerfComparison]  #7  Total: 101, Janky: 4, P99: 9ms
03-01 20:32:59.755 [ButtonPerfComparison]  #8  Total: 101, Janky: 2, P99: 11ms
03-01 20:32:59.755 [ButtonPerfComparison]  #9  Total: 101, Janky: 3, P99: 13ms
03-01 20:32:59.755 [ButtonPerfComparison]  #10  Total: 101, Janky: 5, P99: 10ms
03-01 20:32:59.756 [ButtonPerfComparison]  AVG Total: 99.90, AVG Janky: 4.00, AVG P99: 10.80ms
03-01 20:32:59.756 [ButtonPerfComparison] ════════════════════════════════════════
03-01 20:32:59.757 [ButtonPerfComparison]  HMButtonLegacy (Standard Compose) Results
03-01 20:32:59.757 [ButtonPerfComparison] ════════════════════════════════════════
03-01 20:32:59.758 [ButtonPerfComparison]  #1  Total: 81, Janky: 9, P99: 27ms
03-01 20:32:59.758 [ButtonPerfComparison]  #2  Total: 100, Janky: 9, P99: 25ms
03-01 20:32:59.758 [ButtonPerfComparison]  #3  Total: 102, Janky: 9, P99: 13ms
03-01 20:32:59.759 [ButtonPerfComparison]  #4  Total: 101, Janky: 9, P99: 12ms
03-01 20:32:59.759 [ButtonPerfComparison]  #5  Total: 101, Janky: 9, P99: 12ms
03-01 20:32:59.759 [ButtonPerfComparison]  #6  Total: 100, Janky: 9, P99: 31ms
03-01 20:32:59.759 [ButtonPerfComparison]  #7  Total: 103, Janky: 9, P99: 11ms
03-01 20:32:59.760 [ButtonPerfComparison]  #8  Total: 99, Janky: 7, P99: 23ms
03-01 20:32:59.760 [ButtonPerfComparison]  #9  Total: 103, Janky: 8, P99: 12ms
03-01 20:32:59.760 [ButtonPerfComparison]  #10  Total: 103, Janky: 6, P99: 10ms
03-01 20:32:59.761 [ButtonPerfComparison]  AVG Total: 99.30, AVG Janky: 8.40, AVG P99: 17.60ms
03-01 20:32:59.761 [ButtonPerfComparison] ════════════════════════════════════════
03-01 20:32:59.761 [ButtonPerfComparison]  COMPARISON
03-01 20:32:59.761 [ButtonPerfComparison] ════════════════════════════════════════
03-01 20:32:59.762 [ButtonPerfComparison]  Janky frames improvement: 52.4%
03-01 20:32:59.762 [ButtonPerfComparison]  P99 frame time improvement: 38.6%
03-01 20:32:59.762 [ButtonPerfComparison] ════════════════════════════════════════

1. 단일 버튼 테스트
   Janky 개선율: -12.9 -> 5.0%
   P99 개선율: -5.6 -> 4.9%
2. 60개 버튼 테스트
   Janky 개선율: 52.4%
   P99 개선율: 38.6%

saveLayer에서 RenderNode로 전환함으로써 단일 버튼에서의 성능 역전 현상이 해소되었고, 60개 버튼 스크롤에서는 오히려 P99 개선율이 ShrinkWithGrayBackground(14.3%)보다 크게 향상된 38.6%를 기록했습니다. 이는 Background 드로잉 오버헤드가 완전히 제거된 상태에서 RenderNode 기반 변환만 수행하므로, 순수하게 modifier 체인 통합과 Slot Table 제거의 이점이 반영된 결과입니다.

8. 찐 결론

Modifier.Node로 마이그레이션할 때, Compose가 내부적으로 어떤 렌더링 경로를 사용하는지 이해하는 것이 중요하다는 것을 깨달았습니다. 또한 Unit Test의 커버리지가 실제 성능 비교에 얼마나 중요한지 깊이 깨달았습니다.

감사합니다.

1. 왜 리팩토링이 필요했을까?

기존 코드베이스에서는 각 화면마다 Modifier.clickable을 직접 사용하여 탭 상호작용을 처리했습니다. 이 방식은 몇 가지 문제점을 가지고 있었습니다.

- 일관성 없는 사용자 경험: 화면마다 다른 탭 피드백이 제공되거나, 아예 시각적 피드백이 없는 경우가 발생
- 중복 코드: 동일한 애니메이션 로직이 여러 곳에 반복적으로 작성됨
- 유지보수의 어려움: 탭 애니메이션을 변경하려면 수십 개의 파일을 수정해야 함

이를 해결하기 위해 모든 clickable 수정자를 범용 버튼 컴포넌트로 통합하기로 결정했습니다.

2. 사용자 경험 측면의 고려사항

2.1. Shrink

리팩토링의 가장 큰 과제는 “기존 UI를 해치지 않으면서도 일관된 사용자 경험을 제공하는 것”이었습니다.

기존 clickable 수정자는 단순히 클릭 영역만 제공했기 때문에, 새로운 버튼 컴포넌트가 시각적 변화를 주게 되면 기존 레이아웃이 깨질 수 있었습니다. 특히 다음과 같은 이슈를 고려해야 했습니다.

- 배경이 추가되면 패딩만큼 영역이 확장됨
- 축소 애니메이션이 주변 요소의 배치에 영향을 줄 수 있음

이를 해결하기 위해 대부분의 clickable에는 탭 시, 사이즈가 일시적으로 줄어들어 실제 버튼을 누르는 듯한 시각적 효과인 Shrink를 기본 적용하기로 했습니다.

해당 타입은 추가적인 패딩이나 배경 없이 오직 scale 애니메이션만 제공하여, 기존 레이아웃을 완전히 보존합니다.

2.2. ShrinkWithGrayBackground

배경색이나 border가 존재하여 클릭 여부를 명확히 판단할 수 있는 위 버튼과 달리 영역이 명확하게 보이지 않는 버튼(예: 리스트 아이템 Row)의 경우, 탭했을 때 어떤 영역이 반응하는지 사용자가 알기 어렵습니다.

이를 위해 ShrinkWithGrayBackground 타입을 추가 구현했습니다.

.then(
    if (transitionType == TransitionType.ShrinkWithGrayBackground) {
        Modifier
            .background(
                Color.Gray.copy(alpha = backgroundAlpha.value),
                RoundedCornerShape(8.dp)
            )
            .padding(4.dp) // 최소한의 패딩
    } else {
        Modifier
    }
)

이는 탭 시, scale 효과 뿐만 아니라, 회색계열의 배경색을 띄워 영역을 전달합니다.

2.3. ShrinkWithTilt

마지막으로 일반적인 버튼과 중요한 기능을 수행하는 버튼을 차별화하기 위해 ShrinkWithTilt 타입을 추가했습니다.

if (transitionType == TransitionType.ShrinkWithTilt && componentSize != IntSize.Zero) {
    // 탭 위치를 중심점 기준 상대 좌표로 변환 (-1.0 ~ 1.0)
    val centerX = componentSize.width / 2f
    val centerY = componentSize.height / 2f
    val relativeX = (offset.x - centerX) / (componentSize.width / 2f)
    val relativeY = (offset.y - centerY) / (componentSize.height / 2f)

    // rotationX: Y축 위치에 따라 상하 기울기 (위를 누르면 앞으로, 아래를 누르면 뒤로)
    val targetRotationX = -relativeY * maxTiltAngle
    // rotationY: X축 위치에 따라 좌우 기울기 (왼쪽을 누르면 왼쪽으로, 오른쪽을 누르면 오른쪽으로)
    val targetRotationY = relativeX * maxTiltAngle

    coroutineScope.launch {
        tiltX.animateTo(targetValue = targetRotationX, animationSpec = tween(100))
    }
    coroutineScope.launch {
        tiltY.animateTo(targetValue = targetRotationY, animationSpec = tween(100))
    }
}

앞의 2개 Transition과 달리 탭 위치에 따라 버튼이 물리적으로 눌리는 듯한 효과를 구현하여, 사용자에게 더 생동감 있는 경험을 제공하고자 했습니다.

허나, 효과 자체의 연산량 또한 앞의 2개 Transition보다 더 큰 만큼 버튼의 크기가 크거나 핵심 기능과 직결되는 버튼에 대해서만 이를 사용하고자 했습니다.

3. 성능 최적화: GraphicsLayer의 활용

Compose에서 애니메이션을 구현하는 방법은 크게 두 가지입니다.

// 비효율적
Modifier
    .scale(animatedScale)
    .alpha(animatedAlpha)
    .rotate(animatedRotation)

이 방식은 애니메이션 프레임마다 레이아웃 단계와 Draw 단계를 모두 거치기 때문에 성능 저하를 일으킵니다.

// 효율적
.graphicsLayer {
    alpha = 1f - backgroundAlpha.value
    scaleX = scale.value
    scaleY = scale.value
    if (transitionType == TransitionType.ShrinkWithTilt) {
        rotationX = tiltX.value
        rotationY = tiltY.value
    }
}

그에 반해 graphicsLayer는 GPU 가속 레이어에서 변환을 처리하여 레이아웃 재계산 없이 시각적 변화를 적용합니다.

3. 코드 설명

3.1. tryAwaitRelease

detectTapGestures(
    onPress = { offset ->
        if (!isDisabled) {
            // Press 시작 시 축소 및 배경 표시
            // Press가 끝날 때까지 대기 
            tryAwaitRelease()

            // Release 시 원래 크기로 복원
        }
    },
    onTap = {
        if (!isDisabled) {
            action()
        }
    }
)

사용자가 버튼을 탭할 경우, onPress 콜백이 호출됩니다. 이 때, tryAwaitRelease 메서드를 호출하면 사용자가 손가락을 화면에서 떼기까지 suspend 상태로 호출자를 넘기지 않고 대기합니다.

해당 메서드는 탭 동작이 정상적으로 입력되었는지 여부를 Boolean값으로 반환하기 때문에, 사용자가 최종적으로 손가락을 영역 밖으로 이동 후 놓아 탭 동작을 취소했는지 등을 파악할 수도 있습니다.

3.2. Animatable vs remember { mutableStateOf }

val scale = remember { Animatable(1f) }
val backgroundAlpha = remember { Animatable(0f) }
val tiltX = remember { Animatable(0f) }
val tiltY = remember { Animatable(0f) }

Animatable

1. 애니메이션 취소 및 중단 지원: 사용자가 빠르게 여러 번 탭할 때, 이전 애니메이션을 자동으로 취소하고 새로운 목표값으로 보간을 전환할 수있습니다.
2. Thread-safe: 코루틴 기반으로 안전하게 상태 변경

만약 mutableStateOf를 사용했다면, 빠른 연속 탭 시 애니메이션이 겹쳐서 어색한 동작이 발생할 수 있기에 Animatable을 최종 선택했습니다.

3.3. onSizeChanged

Tilt 효과를 구현하기 위해서는 컴포넌트의 실제 크기를 알아야 탭 위치를 상대 좌표로 변환할 수 있습니다.

var componentSize by remember { mutableStateOf(IntSize.Zero) }

Row(
    modifier = modifier
        .onSizeChanged { size ->
            if (transitionType == TransitionType.ShrinkWithTilt) {
                componentSize = size
            }
        }

버튼의 크기는 컴파일 타임에 알 수 없습니다. content로 전달되는 컴포저블에 따라 크기가 동적으로 결정되기 때문입니다.

onSizeChanged는 레이아웃 측정 후 실제 크기가 확정되면 콜백을 호출하여, 이후 탭 위치 계산에 활용할 수 있게 합니다.

val centerX = componentSize.width / 2f
val centerY = componentSize.height / 2f
val relativeX = (offset.x - centerX) / (componentSize.width / 2f)  // -1.0 ~ 1.0
val relativeY = (offset.y - centerY) / (componentSize.height / 2f) // -1.0 ~ 1.0

최종코드

/**
 * @param modifier 바깥 여백을 padding으로 조절해주세요.
 *        버튼영역에 기본 background값이 있을 경우, BaseButton이 아닌 내부 요소에 직접 적용 후, paddingDp를 0으로 설정해주세요.
 *        modifier에 배경을 적용할 경우, 해당 색상이 차지하는 영역은 graphic layer로 적용되는 scale 애니메이션이 적용되지 않습니다.
 * Press 시 scale과 배경 애니메이션이 적용됩니다.
 * */

object BaseButton {
    enum class TransitionType {
        // 크기가 줄어드는 효과만 제공합니다. 영역이 명확하게 정의된 대부분의 버튼에 적용합니다.
        Shrink,
        // 크기가 줄어드는 효과에 tilt효과를 추가합니다. 큰 feature를 수행하는 버튼에 적용합니다.
        ShrinkWithTilt,
        // 영역이 명확하지 않은 버튼에 제공합니다.
        /** @warning 4 padding이 기본 적용됩니다. */
        ShrinkWithGrayBackground,
    }

    @Composable
    operator fun invoke(
        modifier: Modifier = Modifier,
        action: () -> Unit,
        transitionType: TransitionType = TransitionType.Shrink,
        isDisabled: Boolean = false,
        content: @Composable () -> Unit
    ) {
        val backgroundAlphaTarget = 0.3f
        val scaleTarget = 0.97f
        val maxTiltAngle = 5f

        // Press 애니메이션
        val scale = remember { Animatable(1f) }
        val backgroundAlpha = remember { Animatable(0f) }
        val tiltX = remember { Animatable(0f) }
        val tiltY = remember { Animatable(0f) }
        val coroutineScope = rememberCoroutineScope()

        // 컴포넌트 크기 추적 (ShrinkWithTilt용)
        var componentSize by remember { mutableStateOf(IntSize.Zero) }

        Row(
            modifier = modifier
                .then(
                    if (transitionType == TransitionType.ShrinkWithGrayBackground) {
                        Modifier
                            .background(
                                Color(0xFFE8E8E8).copy(alpha = backgroundAlpha.value),
                                RoundedCornerShape(8.dp)
                            )
                            .padding(4.dp)
                    } else {
                        Modifier
                    }
                )
                .onSizeChanged { size ->
                    if (transitionType == TransitionType.ShrinkWithTilt) {
                        componentSize = size
                    }
                }
                .graphicsLayer {
                    alpha = 1f - backgroundAlpha.value
                    scaleX = scale.value
                    scaleY = scale.value
                    if (transitionType == TransitionType.ShrinkWithTilt) {
                        rotationX = tiltX.value
                        rotationY = tiltY.value
                    }
                }
                .pointerInput(isDisabled) {
                    detectTapGestures(
                        onPress = { offset ->
                            if (!isDisabled) {
                                // Press 시작 시 축소 및 배경 표시
                                coroutineScope.launch {
                                    backgroundAlpha.animateTo(
                                        targetValue = backgroundAlphaTarget,
                                        animationSpec = tween(100)
                                    )
                                }
                                coroutineScope.launch {
                                    scale.animateTo(
                                        targetValue = scaleTarget,
                                        animationSpec = tween(100)
                                    )
                                }

                                if (transitionType == TransitionType.ShrinkWithTilt && componentSize != IntSize.Zero) {
                                    // 탭 위치를 중심점 기준 상대 좌표로 변환 (-1.0 ~ 1.0)
                                    val centerX = componentSize.width / 2f
                                    val centerY = componentSize.height / 2f
                                    val relativeX = (offset.x - centerX) / (componentSize.width / 2f)
                                    val relativeY = (offset.y - centerY) / (componentSize.height / 2f)

                                    // rotationX: Y축 위치에 따라 상하 기울기 (위를 누르면 앞으로, 아래를 누르면 뒤로)
                                    val targetRotationX = -relativeY * maxTiltAngle
                                    // rotationY: X축 위치에 따라 좌우 기울기 (왼쪽을 누르면 왼쪽으로, 오른쪽을 누르면 오른쪽으로)
                                    val targetRotationY = relativeX * maxTiltAngle

                                    coroutineScope.launch {
                                        tiltX.animateTo(
                                            targetValue = targetRotationX,
                                            animationSpec = tween(100)
                                        )
                                    }
                                    coroutineScope.launch {
                                        tiltY.animateTo(
                                            targetValue = targetRotationY,
                                            animationSpec = tween(100)
                                        )
                                    }
                                }

                                // Press가 끝날 때까지 대기
                                tryAwaitRelease()

                                // Release 시 원래 크기로 복원 및 배경 숨김
                                coroutineScope.launch {
                                    scale.animateTo(
                                        targetValue = 1f,
                                        animationSpec = tween(400)
                                    )
                                }
                                coroutineScope.launch {
                                    backgroundAlpha.animateTo(
                                        targetValue = 0f,
                                        animationSpec = tween(400)
                                    )
                                }
                                if (transitionType == TransitionType.ShrinkWithTilt) {
                                    coroutineScope.launch {
                                        tiltX.animateTo(
                                            targetValue = 0f,
                                            animationSpec = tween(400)
                                        )
                                    }
                                    coroutineScope.launch {
                                        tiltY.animateTo(
                                            targetValue = 0f,
                                            animationSpec = tween(400)
                                        )
                                    }
                                }
                            }
                        },
                        onTap = {
                            if (!isDisabled) {
                                action()
                            }
                        }
                    )
                },
            verticalAlignment = Alignment.CenterVertically,
            horizontalArrangement = Arrangement.Center
        ) {
            content()
        }
    }
}

마무리하며

이번 리팩토링을 통해 다음을 달성할 수 있었습니다:

1. 일관된 사용자 경험: 앱 전체에서 통일된 탭 피드백 제공
2. 성능 최적화: GraphicsLayer를 통한 GPU 가속으로 부드러운 애니메이션 구현
3. 유지보수성 향상: 단일 컴포넌트로 모든 탭 상호작용 관리
4. UX 차별화: Tilt 효과를 통한 프리미엄 경험 제공

작은 상호작용 하나하나가 쌓여 전체 앱의 품질을 만든다는 것을 다시 한번 느낄 수 있었습니다. 성능과 UX 사이의 균형을 맞추는 과정이 쉽지는 않았지만, GraphicsLayer와 같은 강력한 API를 활용하면 두 마리 토끼를 모두 잡을 수 있다는 것을 배웠습니다.

감사합니다.

0. 배경: 왜 AI 기반 CI/CD를 도입했는가

소켓통신, 드래그앤드롭과 같은 고도 기능들을 추가함과 동시에 양 플랫폼에 최대한 동일한 사용자 경험을 제공하기 위해 저는 동일한 프로젝트를 각각 iOS와 Android 네이티브 언어로 구현하는 결정을 내리게 되었습니다.

하지만, 점차 프로젝트의 규모가 커지게 되면서 구현 및 유지보수 간, 동기화에 발생하는 비용이 점점 증대되는 것을 체감할 수 있었습니다.

특히, 다음과 같은 문제점이 있었습니다:

- 수동 코드 리뷰의 한계: 리뷰어가 iOS/Android 양쪽 코드를 모두 파악하기 어려움
- 플랫폼 동기화 누락: PR에서 한쪽 플랫폼만 변경해도 알아채기 어려움
- 네이밍 컨벤션 불일치: 시간이 지날수록 플랫폼 간 네이밍이 점점 달라지며, 플랫폼 간 유지보수 비용이 크게 증대됨

이 문제들을 해결하기 위해 Claude Code Action과 Notion MCP를 조합한 자동화 파이프라인을 설계했습니다.

1. 파이프라인 아키텍처 개요

최종 구현된 파이프라인은 크게 3개의 워크플로우로 구성됩니다.

1. Continuous Integration (CI)

Trigger: dev 브랜치에 PR 생성 시

Job 1–2: android-build와 ios-build-test를 병렬 실행

Job 3: claude-code-review
- 플랫폼 간 동기화 비교 및 미반영 확인
- 로직단 미반영 확인
- Code Convention 및 Naming Convention 검토

2. Continuous Deployment (CD)

Trigger: release-{{yymmdd}} 브랜치에서 커밋 및 푸시 수행 시

android-deploy: Firebase App Distribution에 테스트용 APK 자동 배포

ios-deploy: TestFlight에 자동 배포

3. Comprehensive Code Review

Trigger: 매주 토요일 12시 (KST) 자동 실행

comprehensive-code-review:
- Code Convention 및 여태 검증 이슈 축적 검증
- 검증된 이슈를 노션에 KanBan 생성

2. Mobile CI 구현과정

2.1 시행착오와 해결 과정

시행착오 1: 빌드 시간 폭증

초기에는 iOS와 Android 빌드를 순차적으로 실행했습니다.

iOS 빌드: ~15분
Android 빌드: ~10분
-총 소요 시간: 25분+

PR 하나당 25분씩 대기하는 것은 개발 속도를 크게 저하시켰습니다.

이를 해결하고자 병렬 실행으로 전환했습니다.

jobs:
  # 1단계: 빌드 및 테스트 (iOS/Android 병렬 실행)
  build-test-iOS:
    runs-on: self-hosted
    steps:
      - name: Run iOS build and test
        run: |
          xcodebuild clean test \
            -project Humania-iOS/Humania.xcodeproj \
            -scheme Humania-dev \
            -destination 'platform=iOS Simulator,name=iPhone 17,OS=latest'

  build-test-android:
    runs-on: ubuntu-latest
    steps:
      - name: Run Android build and test
        run: |
          cd Humania-android
          bundle exec fastlane android build

병렬 실행으로 전환한 결과, 총 소요 시간이 15분으로 단축되어 40% 시간을 절약할 수 있었습니다.

시행착오 2: Android Gradle 캐시 미스

Android 빌드에서 가장 시간이 오래 걸리는 부분은 Gradle 의존성 다운로드였습니다. 매번 빌드할 때마다 의존성을 새로 다운로드하니 시간이 오래 걸렸습니다.

이를 해결하고자 Gradle 캐싱을 추가해 빌드시간을 10분 -> 7분으로 단축했습니다.

- name: Setup Gradle
  uses: gradle/actions/setup-gradle@v3
  with:
    gradle-version: wrapper
    cache-read-only: false  # 캐시 쓰기 허용

2.3 Claude Code Review

시행착오 3: 리뷰 품질 문제

초기에는 Claude-code-action의 예시로 제시된 프롬프트를 주입하였으나 결과는 너무 일반적이고 표면적인 피드백들이었습니다.

특히, 가장 시간을 많이 잡아먹던 Android와 iOS 간의 플랫폼 동기화 여부 파악에는 실질적인 도움이 되지 않았습니다.

때문에 아래와 같이 제 상황에 최적화된 구체적이고 구조화된 프롬프트를 주입하였습니다. 특히 플랫폼 동기화에 대한 Task를 별도로 명시하였습니다.

- uses: anthropics/claude-code-action@v1
  with:
    prompt: |
      ## Review Instructions
      이 PR에 대해 다음 3가지 관점에서 종합적인 코드 리뷰를 수행해주세요.

      ### 1. 플랫폼 동기화 검토 (Cross-Platform Sync Review)
      **검토 항목**:
      - 한 플랫폼에만 변경사항이 있는 경우, 반대 플랫폼에도 동일한 변경이 필요한지 분석
      - 새로운 API 연동, DTO 추가, UseCase 변경 등이 양 플랫폼에 반영되었는지 확인
      - 도메인 모델 변경 시 양 플랫폼의 모델이 일치하는지 확인

      ### 2. 코드 품질 검토 (Code Quality Review)
      **검토 관점**:
      - 코드 퀄리티 및 Best Practices
      - 버그 및 이슈 발생 가능성
      - 보안 이슈
      - 성능 최적화

      ### 3. 네이밍 컨벤션 검토 (Naming Convention Review)
      위에 제공된 "Naming Convention" 내용을 기준으로 검토해주세요.

시행착오 4: 네이밍 컨벤션 관리의 어려움

처음에는 네이밍 컨벤션을 워크플로우 파일에 .md 파일로 하드코딩했습니다. 하지만 컨벤션이 업데이트될 때마다 여러 워크플로우 파일을 수정해야 했고, 버전 관리가 어려웠습니다.

때문에 Notion을 Single Source of Truth로 활용하고, 워크플로우에서는 Notion API를 직접 호출해 최신 정보를 매번 가져오도록 설계했습니다.

#!/bin/bash
# .github/scripts/fetch-naming-convention.sh

PAGE_ID="2c691349069a806c8694c7af8279d6df"
NOTION_VERSION="2022-06-28"

# Notion API로 블록 가져오기
fetch_blocks() {
  local block_id=$1
  curl -s "https://api.notion.com/v1/blocks/${block_id}/children?page_size=100" \
    -H "Authorization: Bearer ${NOTION_TOKEN}" \
    -H "Notion-Version: ${NOTION_VERSION}"
}

# 블록을 마크다운으로 변환
convert_to_markdown() {
  local blocks_json=$1
  local indent=$2

  echo "$blocks_json" | jq -c '.results[]?' | while read -r block; do
    local block_type=$(echo "$block" | jq -r '.type')
    # ... 각 블록 타입별 변환 로직 ...
  done
}

main() {
  local blocks=$(fetch_blocks "$PAGE_ID")
  echo "# Naming Convention"
  convert_to_markdown "$blocks" ""
}

main

이 스크립트는 Notion API를 통해 네이밍 컨벤션 페이지의 내용을 가져와 마크다운으로 변환합니다.

3. Mobile CD 구현과정

3.1 초기 설계: Fastlane 기반 배포

CD 파이프라인은 Fastlane을 중심으로 설계했습니다. Fastlane은 iOS와 Android 모두를 지원하는 배포 도구입니다.

iOS 배포 파이프라인

# iOS/fastlane/Fastfile
lane :beta do
  setup_ci  # CI 환경 설정

  # Match로 인증서 관리
  match(
    type: "appstore",
    readonly: true
  )

  # 빌드 번호 자동 증가
  increment_build_number

  # 빌드 & 업로드
  build_app(
    scheme: ENV["SCHEME"],
    export_method: "app-store"
  )

  upload_to_testflight(
    skip_waiting_for_build_processing: true
  )
end

Android 배포 파이프라인

# android/fastlane/Fastfile
lane :beta do
  # Firebase App Distribution에 업로드
  firebase_app_distribution(
    app: ENV["APP_ID"],
    groups: "internal-testers",
    release_notes: "Automated build from CI"
  )
end

3.2 인증서 관리

시행착오 5: iOS 인증서

iOS 배포에서 가장 어려웠던 부분은 코드 서명이었습니다. 처음에는 인증서를 수동으로 관리했는데, 다음과 같은 문제가 발생했습니다:

- 팀원마다 다른 인증서 사용
- 인증서 만료 시 모든 기기에서 재설정 필요
- CI 환경에서 인증서 접근 불가

해결책:Fastlane Match를 도입했습니다.

- name: Install SSH key
  uses: shimataro/ssh-key-action@v2
  with:
    key: ${{ secrets.SSH_KEY }}
    known_hosts: ${{ secrets.KNOWN_HOSTS }}
    if_key_exists: replace

- name: Run Fastlane
  run: |
    cd Humania-iOS
    fastlane beta
  env:
    MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}

Match는 인증서를 Git 저장소에 암호화하여 저장하고, 팀원 모두가 동일한 인증서를 사용할 수 있게 해줍니다.

시행착오 6: Android Firebase 인증

Android는 Firebase App Distribution을 사용하는데, 서비스 계정 인증이 필요했습니다. 처음에는 JSON 파일을 직접 저장소에 커밋했다가 보안 경고를 받았습니다.

해결책: Base64 인코딩하여 GitHub Secrets에 저장했습니다.

- name: Create Firebase Service Credentials file
  run: |
    cd Humania-android
    echo "$FIREBASE_CREDENTIALS" > firebase_credentials.json.b64
    base64 -d -i firebase_credentials.json.b64 > firebase_credentials.json
    rm firebase_credentials.json.b64
  env:
    FIREBASE_CREDENTIALS: ${{ secrets.FIREBASE_CREDENTIALS }}

4. Comprehensive Code Review: 정기 검진

4.1 왜 정기 검진의 필요성

PR 단위 리뷰만으로는 충분하지 않았습니다. 시간이 지나면서 아래 문제들이 발생했습니다.

- 네이밍 컨벤션이 서서히 무너짐
- 플랫폼 간 기능 격차 발생
- 기술 부채 누적

이를 해결하기 위해 매주 토요일 자동으로 전체 코드베이스를 점검하는 워크플로우를 만들었습니다.

4.2 Notion MCP: Claude의 새로운 능력

여기서 저는 Claude-code-action에 Notion MCP를 연결하는 선택을 내리게 되었습니다.

MCP(Model Context Protocol)는 Claude가 외부 시스템과 상호작용할 수 있게 해주는 프로토콜입니다. 이를 통해 Claude가 직접 Notion 데이터베이스에 접근 및 Task를 생성할 수 있게 되었습니다.

- name: Create MCP Config
  run: |
    cat > /tmp/mcp-config.json <<EOF
    {
      "mcpServers": {
        "notion": {
          "command": "npx",
          "args": ["-y", "@notionhq/notion-mcp-server@1.9.1"],
          "env": {
            "NOTION_TOKEN": "${{ secrets.NOTION_API_KEY }}"
          }
        }
      }
    }
    EOF

- name: Run comprehensive review with Claude
  uses: anthropics/claude-code-action@v1
  with:
    claude_args: |
      --model claude-sonnet-4-5-20250929
      --mcp-config /tmp/mcp-config.json
      --allowedTools "mcp__notion__API-create-pages,mcp__notion__API-post-page,..."

1. mcpServers: 사용할 MCP 서버 정의 (여기서는 Notion)
2. command: MCP 서버를 실행할 명령어 (npx로 Notion MCP 서버 실행)
3. args: 버전정보를 포함한 Notion MCP 서버 패키지 지정
4. env: Notion API 토큰 전달
5. — allowedTools: Claude가 사용할 수 있는 Notion API 명시

각 권한의 역할

API-retrieve-a-database: 데이터베이스 구조 확인
API-post-database-query: Task 중복 검사
API-create-pages, API-post-page: Task 생성
API-retrieve-a-page, API-get-block-children: 기존 Task 확인
API-patch-block-children, API-update-a-page, API-patch-page: Task 수정

MCP의 역할과 동작 흐름

특히 Claude가 MCP를 통해 생성하는 Task 내부에는 아래와 같은 정보를 포함하도록 프롬프팅하여, 추후 내부 정보를 그대로 복사하여 붙여넣기하는 것만으로 AI에게 Task 컨텍스트 전달이 가능하도록 했습니다.

- 작업명: 무엇을 수정해야 하는지 명확히 표시
- 상태: “AI로 생성됨”으로 설정하여 자동 생성된 Task임을 구분
- 작업팀: iOS/Android 구분하여 책임 소재 명확화
- 우선순위: 위반의 심각도에 따라 자동 설정
- 상세내용: 파일 경로, 현재 코드, 권장 수정안을 포함한 구체적인 가이드

이렇게 생성된 Task는 Notion의 Kanban 보드에서 “AI로 생성됨” 상태로 나타나며, 팀원들이 검토 후 작업을 진행할 수 있습니다.

5. 각 코드의 역할 정리

보안 규정으로 인해 전체 워크플로우 파일은 공유가 힘들다는 점 양해 부탁드립니다.

Mobile CI 워크플로우 구조

# 트리거: PR이 dev 브랜치에 열릴 때
on:
  pull_request:
    branches: [dev]
    types: [opened, reopened]

jobs:
  # Job 1: 빌드 및 테스트 (iOS)
  build-test-iOS:
    runs-on: self-hosted  # Mac Mini 러너 사용
    steps:
      - name: Run iOS build and test
        # Xcode의 xcodebuild 명령으로 빌드 및 테스트
        # - clean: 이전 빌드 산출물 삭제
        # - test: 유닛 테스트 실행
        # - -destination: 시뮬레이터 지정

  # Job 2: 빌드 및 테스트 (Android)
  build-test-android:
    runs-on: ubuntu-latest  # GitHub 호스팅 러너
    steps:
      - name: Setup Gradle
        # Gradle 캐싱으로 빌드 시간 단축
        # cache-read-only: false → 캐시 쓰기 허용

      - name: Run Android build and test
        # Fastlane을 통한 빌드
        # bundle exec: Ruby 번들러를 통해 의존성 격리
        # fastlane android build: Fastfile의 build 레인 실행

  # Job 3: Claude 코드 리뷰
  claude-code-review:
    needs: [build-test-iOS, build-test-android]  # 빌드 성공 후에만 실행
    steps:
      - name: Get Changed Files
        # git diff로 변경된 파일 목록 추출
        # base branch와 head branch 비교

      - name: Fetch Naming Convention from Notion
        # Notion API를 통해 최신 네이밍 컨벤션 가져오기
        # bash 스크립트로 마크다운 변환

      - uses: anthropics/claude-code-action@v1
        # Claude에게 코드 리뷰 요청
        # 1. 플랫폼 동기화 검토
        # 2. 코드 품질 검토
        # 3. 네이밍 컨벤션 검토
        # 결과를 PR 코멘트로 작성

Mobile CD 워크플로우 구조

# 트리거: release-** 브랜치에 푸시될 때
on:
  push:
    branches:
      - release-**

# 동시 실행 방지
concurrency:
  group: mobile-cd-${{ github.ref }}
  cancel-in-progress: false

jobs:
  # Job 1: Android 배포
  android-deploy:
    steps:
      - name: Create Firebase Service Credentials
        # GitHub Secrets에서 Firebase 인증 정보 복호화
        # Base64 디코딩하여 JSON 파일 생성

      - name: Run Fastlane
        # Firebase App Distribution에 APK 업로드
        # 내부 테스터 그룹에 자동 배포

  # Job 2: iOS 배포
  ios-deploy:
    runs-on: self-hosted  # Mac Mini 러너 사용
    steps:
      - name: Install SSH key
        # Match를 위한 SSH 키 설정
        # 암호화된 인증서 저장소 접근

      - name: Run Fastlane
        # 1. Match로 인증서 다운로드
        # 2. 빌드 번호 자동 증가
        # 3. IPA 파일 생성
        # 4. TestFlight에 업로드

Comprehensive Code Review 워크플로우 구조

# 트리거: 매주 토요일 03:00 (UTC) / 12:00 (KST)
on:
  schedule:
    - cron: '0 3 * * 6'

jobs:
  # Job 1: 파일 수집
  collect-codebase-files:
    steps:
      - name: Collect all codebase files by layer
        # find 명령으로 레이어별 파일 목록 수집
        # Domain, Data, Presentation, Infrastructure
        # iOS는 .swift, Android는 .kt 파일

  # Job 2: 종합 리뷰 및 Notion Task 생성
  comprehensive-review-and-notion-task:
    needs: collect-codebase-files
    steps:
      - name: Fetch Naming Convention from Notion
        # 최신 네이밍 컨벤션 가져오기

      - name: Create MCP Config
        # Notion MCP 서버 설정
        # Claude가 Notion API를 사용할 수 있도록 구성

      - uses: anthropics/claude-code-action@v1
        # Claude에게 전체 코드베이스 리뷰 요청
        # 1. 네이밍 컨벤션 위반 사항 수집
        # 2. 플랫폼 동기화 미비점 수집
        # 3. 발견된 이슈를 Notion Task로 생성
        # MCP를 통해 직접 Notion에 작성

6. 성과 배포 주기 안정화

기존의 경우, 기능 개발과 플랫폼간 코드 동기화 작업을 별도 Task로 분리하여 개발을 진행하였습니다. 이러한 순차적 진행방식은 자연스레 앱 배포 주기를 느리게 만들었으며, 하나의 기능을 구현하여 배포하기까지 총 3주의 시간이 걸렸습니다.

하지만, CI를 통해 변경사항에 대한 플랫폼 동기화 여부를 자동 추적할 수 있게 됨에 따라, 기능 구현과 플랫폼 동기화를 병행하여 진행할 수 있게 되었으며, 배포 및 빌드 테스트 자동화 워크플로우로 인해 기능 구현에 대한 주기 또한 앞당길수 있게 되었습니다.

이로 인해 업데이트 배포 주기를 3주에서 1주로 단축시키는 쾌거를 달성했습니다.

7. 마무리하며

iOS와 Android를 동시에 관리하는 프로젝트에서는, 플랫폼 간 동기화가 가장 큰 과제였습니다. Claude Code Action과 Notion MCP를 활용한 자동화를 통해 아래 성과를 거둘 수 있었습니다.

- 플랫폼 간 불일치를 자동으로 감지
- 네이밍 컨벤션 위반을 사전에 차단
- 반복적인 리뷰 작업을 자동화

얻은 교훈

1. AI는 도구일 뿐

Claude가 아무리 뛰어나도, 구체적인 지시사항 없이는 실제 문제를 해결해주지 않았습니다. 때문에, 정확한 프롬프팅을 통해 해결하고자 하는 문제에 대한 컨텍스트를 제공해야만 AI를 효과적으로 활용할 수 있었습니다.

2. Single Source of Truth의 중요성

Notion을 네이밍 컨벤션의 중앙 저장소로 사용하면서, 문서 관리가 획기적으로 개선되었습니다. 때문에, 협업 툴 수정만으로 모든 워크플로우가 자동 반영되어 유지보수 비용을 획기적으로 줄일 수 있었습니다.

감사합니다.

References

- [GitHub Actions Documentation](https://docs.github.com/en/actions)

- [Fastlane Documentation](https://docs.fastlane.tools/)

- [Claude Code Documentation](https://docs.anthropic.com/claude-code)

- [Notion API Documentation](https://developers.notion.com/)

- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)

- [Anthropic Claude Code Action](https://github.com/anthropics/claude-code-action)

1. pointerInput vs dragAndDropTarget

초기에는pointerInput의 detectDragGestures를 사용하여 DnD 콜백을 주입시키고자 했습니다. 하지만, 수정자(Modifier)가 드래그를 가로채는 순간, 해당 Row의 Tap(클릭) 동작이 먹히지 않는 이슈를 마주하게 되었습니다.

저희는 아이템을 클릭해서 상세 바텀시트롤 표시하는 기능과, 길게 눌러 순서를 바꾸는 기능이 공존해야 했습니다. 이를 위해 Compose 1.7에서 도입된 정식 DnD API인 dragAndDropSource와 dragAndDropTarget을 활용하기로 했습니다.

2. onGloballyPositioned 활용

DragAndDropEvent에서 반환하는 y 값을 기준으로 Drop되는 index값을 계산하는 로직을 구현한 결과, 아래와 같이 계산된 index가 조금씩 어긋나는 현상이 발생했습니다.

원인은 DragAndDropEvent에 있었습니다.

DragEvent | API reference | Android Developers

Android 개발자 문서를 확인해 보면, DragEvent.getX() / getY()가 반환하는 값은 전체 화면(Window) 기준입니다. 하지만 우리가 리스트의 인덱스를 계산하기 위해 필요한 값은 Box(컨테이너) 내부의 로컬 좌표입니다.

이를 해결하기 위해 onGloballyPositioned 수정자를 통해 컨테이너의 절대 위치를 지속적으로 추적하여, index 추적에 필요한 y값을 후가공하기로 했습니다.

// containerTopOffset: onGloballyPositioned에서 업데이트되는 원본 상태
var containerTopOffset by remember { mutableFloatStateOf(0f) }
// currentContainerTopOffset: remember 블록 내에서 최신 값을 참조하기 위한 래퍼
val currentContainerTopOffset by rememberUpdatedState(containerTopOffset)

Box(
    modifier = Modifier
        .onGloballyPositioned { coordinates ->
            // Window 기준 Y 좌표 수집
            containerTopOffset = coordinates.positionInRoot().y
        }
        ...
        .dragAndDropTarget(
            shouldStartDragAndDrop = { event ->
              ...
            },
            target = remember {
                object : DragAndDropTarget {
                    override fun onEntered(event: DragAndDropEvent) {
                        val y = event.toAndroidDragEvent().y - currentContainerTopOffset

LayoutCoordinates | API reference | Android Developers

3. 왜 내 Handler는 과거의 데이터만 기억할까…?

구현 중 가장 난해했던 이슈는 리스트가 재정렬되었음에도 불구하고, 드래그를 시작한 아이템이 엉뚱한 ID를 참조하는 현상이었습니다.

드래그되는 컴포저블의 식별자가 제때 갱신되지 않는 것이 원인이라고 가정하고, 아래와 같이 longPress 시 호출되는 콜백이 위치한 dragAndDropSource 내부에 Log를 삽입하여 item.id가 리스트 재정렬 시점에 맞춰 갱신되는지 확인해보고자 했습니다.

Column(Modifier
    .fillMaxSize()
    .verticalScroll(scrollState)) {
    items.forEachIndexed { index, item ->
        DemoItemRow(
            modifier = Modifier
                .height(rowHeight)
                .dragAndDropSource {
                    Log.d("디버깅", "Handler invoked: item.id ${item.id}")
                    detectTapGestures(
                        onTap = { Log.d("디버깅","item: item.id ${item.id}") },
                        onLongPress = {
                            startTransfer(
                                transferData = DragAndDropTransferData(
                                    clipData = ClipData.newPlainText(
                                        "demo/item-id",
                                        item.id.toString()
                                    )
                                )
                            )
                        }
                    )
                },
            item = item,
            isEditMode = true
        )
    }
}

fun DemoItemRow(
    modifier: Modifier = Modifier,
    item: DemoItem,
    isEditMode: Boolean = true
) {
    SideEffect {
        Log.d("디버깅", "Row recomposed: id=${item.id}")
    }

    Row(
        modifier = modifier
            .fillMaxWidth()
            .background(MaterialTheme.colorScheme.surface)
            .padding(horizontal = 16.dp, vertical = 12.dp),
        verticalAlignment = Alignment.CenterVertically
    ) {

디버깅 D  Handler invoked: item.id 1 # 각 Row에 대해 첫 상호작용 시에 핸들러 호출
디버깅 D  item: item.id 1 # 1번째 Row Tap
디버깅 D  Row recomposed: id=2 # 1번째를 2번째 Row 뒤로 Drag and Drop
디버깅 D  Row recomposed: id=1
# 첫번째 Row Tap, 본래 드래그앤드롭이 원활히 실행되려면 이때 Handler가 다시 등록되어야함.
디버깅 D  item: item.id 1 # 이전 Handler가 다시 호출되며 다시 1번째 Row Tap 시 1이 출력됨

Drag and Drop 시, DemoItemRow 자체는 재구성이 발생하는 반면에, 위치 변경 후, 1번째로 위치가 이동된 2번째 Row를 탭하여도, 처음 초기화 당시 해당 위치에 있었던 1번째 Row의 id가 출력되고 있었습니다.

소스 코드를 분석해 본 결과, dragAndDropSource 내부의 DragAndDropSourceNode 구현에서 원인을 찾을 수 있었습니다.

fun Modifier.dragAndDropSource(
    block: suspend DragAndDropSourceScope.() -> Unit
): Modifier = this then DragAndDropSourceWithDefaultShadowElement( // 주목
    dragAndDropSourceHandler = block,
)

// 1. DragAndDropSourceWithDefaultShadowElement
private class DragAndDropSourceWithDefaultShadowElement(
    val dragAndDropSourceHandler: suspend DragAndDropSourceScope.() -> Unit // 주목
) : ModifierNodeElement<DragSourceNodeWithDefaultPainter>() {
    // dragAndDropSourceHandler를 DragSourceNodeWithDefaultPainter에 담아 상호작용 콜백 관리
    override fun create() = DragSourceNodeWithDefaultPainter(
        dragAndDropSourceHandler = dragAndDropSourceHandler,
    )

    override fun update(node: DragSourceNodeWithDefaultPainter) = with(node) {
        dragAndDropSourceHandler =
            this@DragAndDropSourceWithDefaultShadowElement.dragAndDropSourceHandler
    }
    ...
}

// 2. DragSourceNodeWithDefaultPainter
private class DragSourceNodeWithDefaultPainter(
    var dragAndDropSourceHandler: suspend DragAndDropSourceScope.() -> Unit
) : DelegatingNode() {

    init {
        val cacheDrawScopeDragShadowCallback = CacheDrawScopeDragShadowCallback().also {
            delegate(CacheDrawModifierNode(it::cachePicture))
        }
        delegate(
            DragAndDropSourceNode( // 주목
                drawDragDecoration = {
                    cacheDrawScopeDragShadowCallback.drawDragShadow(this)
                },
                dragAndDropSourceHandler = {
                    dragAndDropSourceHandler.invoke(this)
                }
            )
        )
    }
}

internal class DragAndDropSourceNode(
    var drawDragDecoration: DrawScope.() -> Unit,
    var dragAndDropSourceHandler: suspend DragAndDropSourceScope.() -> Unit
) : DelegatingNode(),
    LayoutAwareModifierNode {
    private var size: IntSize = IntSize.Zero

    // init 블록은 한번만 실행되게 보장
    init {
        val dragAndDropModifierNode = delegate(
            DragAndDropModifierNode()
        )

        delegate(
            SuspendingPointerInputModifierNode {
                // node가 attach될 때, 한번 실행되고 이후 suspend 상태 유지
                dragAndDropSourceHandler(...)  // 상호작용 콜백
            }
        )
    }

    override fun onRemeasured(size: IntSize) {
        this.size = size
    }
}

dragAndDropSource는 내부적으로 SuspendingPointerInputModifierNode를 사용합니다.

문제는 init 블록 내에서 실행된 핸들러가 최초 실행 시점의 상태(Stale State)를 캡처한다는 점입니다. 리스트의 순서가 바뀌어 노드가 업데이트되어도, 내부의 코루틴이 유지되고 있다면 과거의 item.id를 계속 쥐고 있게 됩니다. 때문에, dragAndDropSource 수정자 block 내부에서 캡처한 값들은 node가 업데이트 되어도 block은 최초 실행 시점의 값을 계속 유지하게 됩니다.

해결책: key를 통한 노드 재생성 강제

이 문제를 해결하기 위해, Compose의 key를 사용하여 identity를 명확히 부여하여 노드를 업데이트하는 것이 아니라 재생성하기로 했습니다. 이때 key를 어디에 선언하느냐에 따라 성능이 좌우되는 것을 확인할 수 있었습니다.

Case A: 전체 Column에 key(items) 적용 (권장하지 않음)

리스트가 바뀔 때마다 Column 전체를 다시 그립니다. 모든 상태(스크롤 위치 등)가 파괴됩니다.

key(items) {
    Column {
        items.forEachIndexed { index, item ->
            DemoItemRow(...)  // 모든 remember 상태 초기화
        }
    }
}

@Composable
private fun DemoItemRow(item: DemoItem) {
    SideEffect {
        Log.d("디버깅", "Row recomposed: id=${item.id}")
    }
    Row(

D  Row recomposed: id=1
D  Row recomposed: id=2
D  Row recomposed: id=3
D  Row recomposed: id=4
D  Row recomposed: id=5
D  Row recomposed: id=6
D  Row recomposed: id=7
D  Row recomposed: id=8
D  Row recomposed: id=9
D  Row recomposed: id=10
D  Row recomposed: id=11
D  Row recomposed: id=12
D  Row recomposed: id=13
D  Row recomposed: id=14
D  Row recomposed: id=15
D  Row recomposed: id=16
D  Row recomposed: id=17
D  Row recomposed: id=18
D  Row recomposed: id=19
D  Row recomposed: id=20 # 초기 구성 작업 완료
# 드래그앤 드롭 수행
D  Row recomposed: id=2 
D  Row recomposed: id=1
D  Row recomposed: id=3
D  Row recomposed: id=4
D  Row recomposed: id=5
D  Row recomposed: id=6
D  Row recomposed: id=7
D  Row recomposed: id=8
D  Row recomposed: id=9
D  Row recomposed: id=10
D  Row recomposed: id=11
D  Row recomposed: id=12
D  Row recomposed: id=13
D  Row recomposed: id=14
D  Row recomposed: id=15
D  Row recomposed: id=16
D  Row recomposed: id=17
D  Row recomposed: id=18
D  Row recomposed: id=19
D  Row recomposed: id=20 # 드래그 앤드롭 시에도, 모든 Row가 재구성되고 있음!

items 리스트 변경 시, key가 변경됨에 따라, Column 전체가 새 Composable로 인식되며 모든 remember 상태 파괴 및 재생성됩니다. 이 과정에서 스크롤 위치, 애니메이션 상태가 모두 초기화됩니다.

Case B: 각 Row에 key(item.id) 적용 (최적)

리스트 내에서 아이템의 위치가 바뀌어도 각 Row는 고유한 identity를 유지합니다. 상태가 이동(Move)되면서 Modifier Node가 새로 등록되어 Stale 데이터 문제가 해결됩니다.

Column(Modifier.verticalScroll(scrollState)) {
    items.forEachIndexed { index, item ->
        key(item.id) { // Row별 identity 부여로 노드 재생성 유도
            DemoItemRow(...) 
        }
    }
}

D  Row recomposed: id=1
D  Row recomposed: id=2
D  Row recomposed: id=3
D  Row recomposed: id=4
D  Row recomposed: id=5
D  Row recomposed: id=6
D  Row recomposed: id=7
D  Row recomposed: id=8
D  Row recomposed: id=9
D  Row recomposed: id=10
D  Row recomposed: id=11
D  Row recomposed: id=12
D  Row recomposed: id=13
D  Row recomposed: id=14
D  Row recomposed: id=15
D  Row recomposed: id=16
D  Row recomposed: id=17
D  Row recomposed: id=18
D  Row recomposed: id=19
D  Row recomposed: id=20 # 초기 구성 작업 완료
# 드래그앤드롭 실행
# 더이상 재구성이 발생하지 않음

3. LazyColumn을 포기한 이유: 강제 스크롤 Glitch

효율적인 리스트 렌더링을 위해 처음에는 LazyColumn을 선택했습니다. 허나 , 이와 관련하여 치명적인 UX 이슈를 발견했습니다.

1. 상단 이동 시 튐 현상: 첫 번째 요소를 아래로 드래그하면, 이동된 위치에 맞춰 화면의 scrollOffset이 강제로 변경되었습니다.
2. 아이템 가려짐: 첫 번째 요소 위로 다른 아이템을 드래그할 경우, 아이템이 화면 밖으로 가려지는 현상이 발생했습니다.

원인은 LazyListState 내부의 updateScrollPositionIfTheFirstItemWasMoved 메서드 때문이었습니다. 아이템의 ID(key)가 유지된 채 인덱스만 바뀌면, Compose는 사용자가 보고 있는 첫 번째 아이템을 유지하려 스크롤을 강제로 조정합니다.

How to prevent LazyColumn from autoscrolling if the first item was moved

1차 해결 시도: scrollToItem 보정 (실패)

override fun onDrop(event: DragAndDropEvent): Boolean {
    // ... 아이템 데이터 추출 로직 ...
    
    val y = event.toAndroidDragEvent().y
    val at = computeTargetIndex(y)
    val currentIndex = items.indexOfFirst { it.id == draggedId }
    // 이동 후 예상되는 인덱스 계산
    val predictedInsertIndex = if (currentIndex != -1) {
        if (currentIndex < at) (at - 1).coerceIn(0, items.size - 1)
        else at.coerceIn(0, items.size - 1)
    } else at
    // 실제 아이템 이동 콜백 실행
    moveItem(droppedItem, at)
    // 드롭 완료 후 해당 위치로 강제 스크롤 보정
    scrollScope.launch {
        if (items.isNotEmpty()) {
            listState.animateScrollToItem(
                index = predictedInsertIndex,
                scrollOffset = 0
            )
        }
    }
    return true
}

드롭 직후 scrollToItem을 호출하여 오프셋을 재조정하려 했으나, 드롭 직후 화면이 glitch되는 현상이 발생해, 리스트가 재정렬되었는지 사용자가 혼란을 느끼는 결과를 초래했습니다.

최종 해결: Column 전환과 커스텀 애니메이션

결국 성능과 UX 사이의 트레이드오프 끝에, LazyColumn을 포기하고 Column + verticalScroll 조합으로 선회했습니다. 제가 타겟팅하는 화면에서는 아이템 수의 상한선이 정해져있었기에 가능한 결정이었습니다.

4. 최종구현

기본적인 DnD기능을 구현한 후에는 재사용이 가능한 CustomDraggableList로 구현하였습니다. SwiftUI와 달리 Compose는 양방향 데이터 흐름이 기본이 아니기에, 상태 변경을 외부로 위임하는 콜백 구조를 설계했습니다.

• Draggable 인터페이스를 상속받은 어떤 데이터 모델이든 수용 가능하도록 제네릭 타입 T 을 사용토록 설계했습니다.
• 아이템과 목적지 인덱스를 전달하여 원본 리스트를 직접 수정할 수 있도록 onReorder 콜백을 추가했습니다.
• 리스트 상/하단에 유연하게 header와 footer를 삽입할 수 있도록 범용성을 증대했습니다.

/**
 * @param items 리스트에 표시할 아이템 목록
 * @param rowHeight 각 행의 고정 높이
 * @param isDragEnabled 드래그 기능 활성화 여부
 * @param onReorder 아이템 재정렬 완료 시 호출되는 콜백 (item, insertIndex)
 */
@Composable
fun <T : Draggable> CustomDraggableList(
    items: List<T>,
    rowHeight: Dp,
    isDragEnabled: Boolean,
    onReorder: (T, Int) -> Unit,
    onTapRow: (T) -> Unit,
    itemContent: @Composable (T, Boolean) -> Unit,
    header: @Composable (() -> Unit)? = null,
    footer: @Composable (() -> Unit)? = null,
    listState: LazyListState = rememberLazyListState(),
    modifier: Modifier = Modifier
) { ... }

애니메이션 구현

1. Row 재정렬 애니메이션

Column은 LazyColumn의 Modifier.animateItem()을 지원하지 않습니다. 이를 해결하기 위해 Animatable과 graphicsLayer를 조합하여 직접 인덱스 변경에 따른 이동 애니메이션을 구현했습니다.

items.forEachIndexed { index, item ->
    key(item.id) {
        var previousIndex by remember { mutableIntStateOf(index) }
        val offsetY = remember { Animatable(0f) }
        LaunchedEffect(index) {
            if (previousIndex != index) {
                // 이전 인덱스와 현재 인덱스 차이를 계산하여 델타값 도출
                val delta = (previousIndex - index) * (rowHeightPx + gapPx)
                offsetY.snapTo(delta)
                // 0(새로운 위치)으로 부드럽게 복귀
                offsetY.animateTo(0f, spring(dampingRatio = 0.8f, stiffness = 300f))
                previousIndex = index
            }
        }
        Column(Modifier.graphicsLayer { translationY = offsetY.value }) {
            itemContent(item, isDragging)
        }
    }
}

2. 드롭 인디케이터 표시/미표시 애니메이션

애니메이션을 구현하면서 가장 고민했던 부분은 “어떻게 하면 아이템이 밀려나고 들어가는 과정이 iOS처럼 자연스러울까?” 하는 점이었습니다. 이 과정에서 SwiftUI와 Jetpack Compose의 애니메이션 구동 로직 차이를 명확히 체감할 수 있었습니다.

SwiftUI: 선언적 ‘결과’에 대한 자동 보간

SwiftUI에서는 .animation(.spring(), value: items) 코드 한 줄이면 충분합니다. 시스템이 뷰의 이전 상태와 다음 상태를 비교하여, 뷰가 차지하는 영역(Layout Area)의 변화를 포함한 모든 요소에 대해 알아서 보간법을 적용해 줍니다.

Jetpack Compose: 명시적 ‘전환’의 설계

반면 Jetpack Compose는 애니메이션 내용을 개발자가 명시적으로 선언해야 합니다. 단순히 “값이 바뀌었으니 알아서 그려줘”가 아니라, “이 영역이 나타날 때 어떤 물리적 특성을 가질 것인가”를 지정해야 합니다.

• fadeIn / fadeOut의 한계: 단순히 투명도만 조절할 경우, 드롭 인디케이터가 생성될 때 주변 아이템들이 즉각적으로 위치를 이동해 버려 화면이 툭툭 끊기는 느낌을 줍니다.
• expandVertically / shrinkVertically의 활용: 드롭 인디케이터에 이 보간법을 적용하면, 실제 뷰의 높이값이 0에서부터 스프링 물리 법칙에 따라 점진적으로 증가합니다. 이때 Compose의 레이아웃 엔진은 변화하는 높이를 실시간으로 측정하여 하위 아이템들을 부드럽게 밀어냅니다.

val transitionDuration = 120
AnimatedVisibility(
    visible = targetedDropIndex == index,
    // fadeIn보다 expandVertically를 사용하여 영역 할당 자체를 애니메이션화
    enter = expandVertically(tween(transitionDuration)), 
    exit = shrinkVertically(tween(transitionDuration)),
) {
    dropIndicator()
}

결국 Jetpack Compose에서의 DnD는 단순한 위치 이동을 넘어, 레이아웃의 변화를 어떻게 프레임 단위로 쪼개어 보여줄 것인가에 대한 설계가 핵심이었습니다. 명시적으로 선언해야 한다는 점은 번거로울 수 있지만, 반대로 말하면 물리적인 디테일을 개발자가 완벽하게 통제할 수 있다는 강력한 장점이 됩니다.

3. Tap 피드백 애니메이션

DnD 기능 구현 과정에서 또 하나 중요한 UX 개선 포인트를 발견했습니다. 바로 일반 Tap과 Long Press 사이의 피드백 문제였습니다.

dragAndDropSource 내부의 detectTapGestures는 사용자가 LongPress를 수행할 때까지 아무런 시각적 피드백을 제공하지 않습니다. 때문에, 사용자의 탭 동작이 드래그로 이어지고 있는지를 0.3초가 지나서야 알수 있다는 한계가 존재했습니다.

해결책: 탭 시작 즉시 피드백 제공

이를 해결하기 위해, 이전에 구현한 탭 애니메이션 ShrinkWithGrayBackground 스타일을 리스트 아이템에 동일하게 적용하였습니다.

[Jetpack Compose] 우아한 버튼 탭 애니메이션 구현하기

최종 코드

/**
 * 드래그 앤 드롭으로 아이템 순서를 변경할 수 있는 리스트 컴포넌트.
 *
 * 주요 기능:
 * - Android의 Drag and Drop API를 사용하여 네이티브 드래그 동작을 지원합니다.
 * - 드래그 시 해당 행이 [Primary10] 배경으로 하이라이트되고, 햅틱 피드백이 제공됩니다.
 * - 드래그 중 리스트 상하단에 도달하면 자동 스크롤이 활성화됩니다.
 * - 아이템 순서 변경 시 spring 애니메이션으로 부드러운 전환 효과가 적용됩니다.
 * - [isDragEnabled]가 false이면 드래그가 비활성화되고 탭만 동작합니다.
 *
 * 아이템은 [Draggable] 인터페이스를 구현해야 하며, [id] 프로퍼티로 각 아이템을 식별합니다.
 *
 * @param T [Draggable]을 구현하는 아이템 타입.
 * @param modifier 리스트에 적용할 Modifier.
 * @param items 리스트에 표시할 아이템 목록.
 * @param rowHeight 각 행의 고정 높이. 드래그 위치 계산에 사용됩니다.
 * @param isDragEnabled 드래그 기능 활성화 여부
 * @param onReorder 아이템 재정렬 완료 시 호출되는 콜백 (item, targetIndex)
 * @param onTapRow 행 탭 시 호출되는 콜백
 * @param itemContent 각 아이템의 컨텐츠를 생성하는 composable (item, isDragging)
 * @param header 리스트 상단에 표시할 헤더 컴포저블
 * @param footer 리스트 하단에 표시할 푸터 컴포저블
 * @param scrollState ScrollState (외부에서 주입 가능)
 * @param modifier Modifier
 */
interface Draggable {
    val id: Int
}

@OptIn(ExperimentalFoundationApi::class)
@Composable
fun <T : Draggable> NeoDraggableList(
    modifier: Modifier = Modifier,
    items: List<T>,
    rowHeight: Dp,
    isDragEnabled: Boolean,
    onReorder: (T, Int) -> Unit,
    onTapRow: (T) -> Unit,
    itemContent: @Composable (T, Boolean) -> Unit,
    header: @Composable (() -> Unit)? = null,
    footer: @Composable (() -> Unit)? = null
) {
    val scrollState = rememberScrollState()
    val density = LocalDensity.current
    val hapticFeedback = LocalHapticFeedback.current
    val overallHeightPx = with(density) { (rowHeight + DROP_INDICATOR_HEIGHT + DROP_INDICATOR_ROW_GAP).toPx() }

    val currentItems by rememberUpdatedState(items)
    val currentOnReorder by rememberUpdatedState(onReorder)

    // 드롭 타겟 인덱스 (items 리스트 기준, 0..items.size)
    var targetedDropIndex by remember { mutableStateOf<Int?>(null) }
    var prevTargetedDropIndex by remember { mutableStateOf<Int?>(null) }

    // 자동 스크롤 속도
    var autoScrollVelocity by remember { mutableFloatStateOf(0f) }

    // 마지막 드래그 Y 좌표 (Window 기준)
    var lastDragY by remember { mutableStateOf<Float?>(null) }

    // 드래그 중인 아이템 ID 추적 (시각적 피드백용)
    var draggingItemId by remember { mutableStateOf<Int?>(null) }

    // 컨테이너의 Window 기준 Y 오프셋 및 높이
    var containerTopOffset by remember { mutableFloatStateOf(0f) }
    var containerHeight by remember { mutableFloatStateOf(0f) }

    // 헤더 높이 (computeTargetIndex에서 사용)
    var headerHeightPx by remember { mutableFloatStateOf(0f) }

    // ========================================
    // 자동 스크롤 속도 계산
    // ========================================
    fun updateAutoScrollVelocity() {
        val y = lastDragY
        if (y == null) {
            autoScrollVelocity = 0f
            return
        }
        val toTop = y - containerTopOffset
        val toBottom = (containerTopOffset + containerHeight) - y

        val scrollThresholdPx = with(density) { SCROLL_THRESHOLD_DP.toPx() }
        val headerThresholdPx = with(density) { HEADER_THRESHOLD_DP.toPx() }

        autoScrollVelocity = when {
            toTop < (scrollThresholdPx + headerThresholdPx) -> -SCROLL_VELOCITY
            toBottom < scrollThresholdPx -> SCROLL_VELOCITY
            else -> 0f
        }
    }

    // ========================================
    // 프레임 동기화 자동 스크롤 루프
    // ========================================
    LaunchedEffect(scrollState) {
        var lastTime = 0L
        while (isActive) {
            val dtNanos = withFrameNanos { now ->
                val dt = if (lastTime == 0L) 0L else now - lastTime
                lastTime = now
                dt
            }
            val v = autoScrollVelocity
            if (v != 0f && dtNanos > 0L) {
                val dtSec = dtNanos / 1_000_000_000f
                val delta = v * dtSec
                val consumed = scrollState.scrollBy(delta)
                if (abs(consumed) < 0.5f) {
                    autoScrollVelocity = 0f
                }
            }
        }
    }

    LaunchedEffect(targetedDropIndex) {
        if (prevTargetedDropIndex != targetedDropIndex && targetedDropIndex != null) {
            hapticFeedback.performHapticFeedback(HapticFeedbackType.LongPress)
        }
        prevTargetedDropIndex = targetedDropIndex
    }

    // ========================================
    // 드롭 타겟 인덱스 계산 (items 리스트 기준 인덱스 반환)
    //
    // Window Y → 컨테이너 로컬 Y → 스크롤 보정한 절대 Y → 헤더 제외 → rowHeight로 인덱스 계산
    // ========================================
    fun computeTargetIndex(y: Float): Int {
        return DraggableListLogic.computeTargetSlot(
            windowY = y,
            containerTopOffset = containerTopOffset,
            scrollOffset = scrollState.value,
            headerHeightPx = headerHeightPx,
            rowSlotHeightPx = overallHeightPx,
            itemCount = currentItems.size
        )
    }

    fun moveItem(item: T, targetItemsIndex: Int) {
        val currentIndex = currentItems.indexOfFirst { it.id == item.id }
        if (currentIndex == -1) return
        val insertIndex = DraggableListLogic.computeInsertIndex(
            currentIndex = currentIndex,
            targetSlot = targetItemsIndex,
            itemCount = currentItems.size
        )
        currentOnReorder(item, insertIndex)
    }

    // region SubComponent
    @Composable fun dropIndicator() {
        Box(
            modifier = Modifier
                .fillMaxWidth()
                .height(DROP_INDICATOR_HEIGHT)
                .background(Primary10, RoundedCornerShape(4.dp))
        )
    }
    Box(
        modifier = modifier
            .fillMaxSize()
            .onGloballyPositioned { coordinates ->
                containerTopOffset = coordinates.positionInRoot().y
                containerHeight = coordinates.size.height.toFloat()
            }
            .dragAndDropTarget(
                shouldStartDragAndDrop = { event ->
                    event.mimeTypes().contains(ClipDescription.MIMETYPE_TEXT_PLAIN)
                },
                target = remember {
                    object : DragAndDropTarget {
                        override fun onEntered(event: DragAndDropEvent) {
                            val y = event.toAndroidDragEvent().y
                            lastDragY = y
                            targetedDropIndex = computeTargetIndex(y)
                        }

                        override fun onMoved(event: DragAndDropEvent) {
                            val y = event.toAndroidDragEvent().y
                            lastDragY = y
                            updateAutoScrollVelocity()
                            targetedDropIndex = computeTargetIndex(y)
                        }

                        override fun onExited(event: DragAndDropEvent) {
                            autoScrollVelocity = 0f
                            lastDragY = null
                            targetedDropIndex = null
                            draggingItemId = null
                        }

                        override fun onEnded(event: DragAndDropEvent) {
                            autoScrollVelocity = 0f
                            lastDragY = null
                            targetedDropIndex = null
                            draggingItemId = null
                        }

                        override fun onDrop(event: DragAndDropEvent): Boolean {
                            val text = event.toAndroidDragEvent().clipData
                                ?.getItemAt(0)?.text?.toString()
                            val draggedId = text?.toIntOrNull() ?: return false
                            val droppedItem = currentItems.firstOrNull { it.id == draggedId } ?: return false

                            val dropSlot = targetedDropIndex ?: computeTargetIndex(event.toAndroidDragEvent().y)
                            moveItem(droppedItem, dropSlot)
                            targetedDropIndex = null
                            draggingItemId = null
                            return true
                        }
                    }
                }
            )
    ) {
        Column(
            modifier = Modifier
                .fillMaxSize()
                .verticalScroll(scrollState),
            verticalArrangement = Arrangement.spacedBy(0.dp)
        ) {
            header?.let {
                Box(Modifier.onGloballyPositioned { coordinates ->
                    headerHeightPx = coordinates.size.height.toFloat()
                }
                ) { it() }
            }

            items.forEachIndexed { index, item ->
                key(item.id) {
                    // 리오더 애니메이션: 인덱스 변경 시 이전 위치에서 새 위치로 슬라이드
                    var previousIndex by remember { mutableIntStateOf(index) }
                    val offsetY = remember { Animatable(0f) }

                    LaunchedEffect(index) {
                        if (previousIndex != index) {
                            // index * Row 높이로 하여 애니메이션이 진행될 offsetPx을 계산
                            val delta = (previousIndex - index) * overallHeightPx
                            // 기존 변경된 위치에서,
                            offsetY.snapTo(delta)
                            // 새로 변경된 위치로 애니메이션 진행
                            offsetY.animateTo(
                                targetValue = 0f,
                                animationSpec = spring(
                                    dampingRatio = 0.8f,
                                    stiffness = 300f
                                )
                            )
                            previousIndex = index
                        }
                    }

                    val isLast = index==(items.size-1)

                    // 눌림 효과를 위한 scale 애니메이션
                    val scale = remember { Animatable(1f) }
                    // Press 시 배경 alpha 애니메이션
                    val backgroundAlpha = remember { Animatable(0f) }
                    val coroutineScope = rememberCoroutineScope()

                    Column(
                        Modifier
                            .height(rowHeight+ DROP_INDICATOR_HEIGHT + DROP_INDICATOR_ROW_GAP +
                                    (if (isLast) (DROP_INDICATOR_HEIGHT + DROP_INDICATOR_ROW_GAP) else 0.dp)
                            ) // 순수 Row Height + DropIndicator
                            .fillMaxWidth()
                            .padding(horizontal = 16.dp)
                            .background(
                                Gray25.copy(alpha = backgroundAlpha.value),
                                RoundedCornerShape(8.dp)
                            )
                            .padding(4.dp)
                            .graphicsLayer {
                                alpha = 1f - backgroundAlpha.value
                                translationY = offsetY.value
                                scaleX = scale.value
                                scaleY = scale.value
                            }
                            .then(
                                if (isDragEnabled) {
                                    Modifier
                                        .dragAndDropSource {
                                            detectTapGestures(
                                                onPress = {
                                                    // Press 시작 시 축소 및 배경 표시
                                                    coroutineScope.launch {
                                                        scale.animateTo(
                                                            targetValue = 0.97f,
                                                            animationSpec = tween(100)
                                                        )
                                                    }
                                                    coroutineScope.launch {
                                                        backgroundAlpha.animateTo(
                                                            targetValue = 0.3f,
                                                            animationSpec = tween(100)
                                                        )
                                                    }
                                                    // Press가 끝날 때까지 대기
                                                    tryAwaitRelease()
                                                    // Release 시 원래 크기로 복원 및 배경 숨김
                                                    coroutineScope.launch {
                                                        scale.animateTo(
                                                            targetValue = 1f,
                                                            animationSpec = tween(400)
                                                        )
                                                    }
                                                    coroutineScope.launch {
                                                        backgroundAlpha.animateTo(
                                                            targetValue = 0f,
                                                            animationSpec = tween(400)
                                                        )
                                                    }
                                                },
                                                onTap = { onTapRow(item) },
                                                onLongPress = {
                                                    hapticFeedback.performHapticFeedback(HapticFeedbackType.LongPress)
                                                    draggingItemId = item.id
                                                    startTransfer(
                                                        transferData = DragAndDropTransferData(
                                                            clipData = ClipData.newPlainText(
                                                                "draggable-item-id",
                                                                item.id.toString()
                                                            )
                                                        )
                                                    )
                                                }
                                            )
                                        }
                                } else {
                                    Modifier
                                }
                            ),
                        verticalArrangement = Arrangement.spacedBy(DROP_INDICATOR_ROW_GAP)
                    ) {
                        val transitionDuration = 120
                        AnimatedVisibility(
                            visible = targetedDropIndex == index,
                            enter = expandVertically(tween(transitionDuration)),
                            exit = shrinkVertically(tween(transitionDuration)),
                        ) {
                            dropIndicator()
                        }
                        Column(Modifier.height(rowHeight)) {
                            itemContent(item, draggingItemId == item.id)
                        }
                        AnimatedVisibility(
                            visible = isLast && targetedDropIndex == index + 1,
                            enter = expandVertically(tween(transitionDuration)),
                            exit = shrinkVertically(tween(transitionDuration)),
                        ) {
                            dropIndicator()
                        }
                    }
                }
            }
            footer?.let { it() }
        }
    }
}

private val SCROLL_THRESHOLD_DP = 96.dp
private val HEADER_THRESHOLD_DP = 64.dp
private val DROP_INDICATOR_HEIGHT = 12.dp
private val DROP_INDICATOR_ROW_GAP = 4.dp
private const val SCROLL_VELOCITY = 1200f

/**
 * DnD 재정렬 로직의 순수 계산 함수.
 * Composable 내부 로컬 함수와 동일한 로직을 외부에서 테스트할 수 있도록 분리.
 */
internal object DraggableListLogic {

    /**
     * Window Y 좌표 → 드롭 슬롯 인덱스 (0..itemCount) 변환.
     * Composable 내부 computeTargetIndex와 동일한 로직.
     */
    fun computeTargetSlot(
        windowY: Float,
        containerTopOffset: Float,
        scrollOffset: Int,
        headerHeightPx: Float,
        rowSlotHeightPx: Float,
        itemCount: Int
    ): Int {
        val localY = windowY - containerTopOffset
        val absoluteY = localY + scrollOffset
        val relativeY = absoluteY - headerHeightPx
        if (relativeY <= 0f) return 0

        val index = (relativeY / rowSlotHeightPx).toInt()
        val midOffset = relativeY - (index * rowSlotHeightPx)
        val adjustedIndex = if (midOffset > rowSlotHeightPx / 2f) index + 1 else index
        return adjustedIndex.coerceIn(0, itemCount)
    }

    /**
     * 드롭 슬롯 → 실제 삽입 인덱스 변환.
     * Composable 내부 moveItem과 동일한 로직.
     */
    fun computeInsertIndex(
        currentIndex: Int,
        targetSlot: Int,
        itemCount: Int
    ): Int {
        val coercedTarget = targetSlot.coerceIn(0, itemCount)
        return if (coercedTarget > currentIndex) coercedTarget - 1 else coercedTarget
    }
}

마무리하며

이번 DnD 구현 과정은 Jetpack Compose의 좌표 시스템과 Modifier Node의 생명주기를 깊게 이해할 수 있는 좋은 계기였습니다. 화려한 UI 뒤에는 노드의 재생성 메커니즘과 같은 로우 레벨에 대한 고민이 필수적이라는 것을 느꼈습니다.

감사합니다.

0. 구현 배경

초기에는 iOS 16에서 제공하는 dropDestination을 통해 순서 정렬 로직을 구성하였습니다.

본래 구현 목표는 사용자가 드래그 도중 ItemRow 위를 이동할때, ItemRow의 상단 영역과 하단영역에 따라 각기 다른 Indicator가 show/hide되도록 구현하고자 했습니다.

이를 위해 체이닝된 뷰에 드래그 동작으로 진입하였는지 여부를 추적하는dropDestination의 isTargeted 콜백을 사용하고자 하였으나 해당 콜백은 진입여부에 대한 isTargeted 값만 접근이 가능했기에, 진입 당시 사용자가 ItemRow의 상단에 있는지 하단에 있는지 확인할 수 없었습니다.

  // dropDestination의 한계 - 위치 정보 없이 진입 여부만 제공
  .dropDestination(for: Item.self) { droppedItems, _ in
      // 드롭 처리
      return true
  } isTargeted: { isTargeted in
      // Bool 값만 제공 - 상단/하단 구분 불가
      targetedDropIndex = isTargeted ? index : nil
  }

이를 위해 상단과 하단으로 총 2개의 dropDestination을 ItemRow내부에 overlay와 background 뷰 수정자를 통해 배치시켜 드래그 도중 위치를 추적해보려 했지만, ItemRow 자체에서도 Tap 동작을 listen하고 있어야 했기에 두 상호작용 추적 로직이 충돌하는 이슈가 있었습니다.

때문에, 최종적으로 ItemRow 간 얇은 Spacer를 dropDestination으로 설정하는 방향으로 최종 구현을 결정지었습니다.

  // LegacyDraggableList - ItemRow 사이에 별도의 dropZone 배치
  LazyVStack(spacing: 0) {
      dropZone(at: 0)  // 첫 번째 드롭존
      ForEach(Array(items.enumerated()), id: \.element.id) { index, item in
          VStack(spacing: 0) {
              itemContent(item, false)
                  .padding(.bottom, 12)
                  .background(
                      dropZone(at: index + 1),  // 각 아이템 하단에 드롭존
                      alignment: .bottom
                  )
          }
      }
      ...

하지만 이를 사용하면서 사용자 경험 측면에서 2가지 문제가 존재했습니다.

1. 0.3초 이상 longPress해야 drag 동작이 호출되는데, 처음에 탭 상호작용이draggable 뷰 수정자까지 정상적으로 소비되지 않을 경우 onStartDrag 동작으로 이어지지 않았고, 0.3초가 지날때까지 이를 사용자가 파악할 수 있는 시각적 피드백이 부재했습니다.

2. ItemRow 내부에 Drop을 할 경우에는, 순서 재정렬이 되지 않아. 사이 공간에 드래그 위치를 맞춰야하는 번거로움이 존재했습니다.

때문에, 이러한 사용자 경험 관련 문제를 해결하고자, 아래 기준을 충족하는 커스텀 DraggableList를 생성하게 되었습니다.

구현 조건:
- ItemRow에 탭 상호작용이 도달
- 드래그 도중 어느 곳에서 드래그를 멈추던 순서 재정렬 수행
- 드래그로 연결이 되고 있는지의 여부 전달을 위한 첫 터치에 대한 시각적 피드백 제공

1. dropDestination 대신 onDrop + DropDelegate 사용

1.1 왜 DropDelegate인가요?

DropDelegate는 드롭을 허용하도록 수정된 뷰에서 드롭 작업과 상호 작용하기 위해 구현된 인터페이스입니다.

dropDestination은 iOS 16에서 도입된 간편한 API이지만, 드래그 중인 아이템의 정확한 좌표 정보에 접근할 수 없다는 한계가 있습니다. 반면
DropDelegate 프로토콜은 DropInfo 객체를 통해 드래그 위치를 실시간으로 추적이 가능했습니다.

// DropDelegate 프로토콜의 주요 메서드
 protocol DropDelegate {
   func dropEntered(info: DropInfo) // 드롭 영역 진입
   func dropUpdated(info: DropInfo) -> DropProposal? // 드래그 중 위치 업데이트
   func dropExited(info: DropInfo) // 드롭 영역 이탈
   func performDrop(info: DropInfo) -> Bool // 드롭 수행
 }

핵심은 DropInfo.location 프로퍼티입니다. 이를 통해 드래그 중인 아이템이 현재 뷰의 어느 위치에 있는지 CGPoint 좌표로 확인할 수 있습니다.

1.2 ItemDropDelegate 구현

struct ItemDropDelegate<Item: Draggable>: DropDelegate {
      let index: Int
      let rowHeight: CGFloat
      let onUpdateTarget: (Int?) -> Void
      let onDrop: (Item, Int) -> Void

      // 드래그가 영역에 진입했을 때
      func dropEntered(info: DropInfo) {
          updateTargetIndex(for: info.location)
      }

      // 드래그 중 위치가 업데이트될 때 (핵심!)
      func dropUpdated(info: DropInfo) -> DropProposal? {
          updateTargetIndex(for: info.location)
          return DropProposal(operation: .move)
      }

      // 드래그가 영역을 벗어났을 때
      func dropExited(info: DropInfo) {
          onUpdateTarget(nil)
      }

      // 드롭이 수행되었을 때
      func performDrop(info: DropInfo) -> Bool {
          let isTopHalf = info.location.y < rowHeight / 2
          let targetIndex = isTopHalf ? index : index + 1

          guard let itemProvider = info.itemProviders(for: [.data]).first else {
              onUpdateTarget(nil)
              return false
          }

          _ = itemProvider.loadTransferable(type: Item.self) { result in
              DispatchQueue.main.async {
                  switch result {
                  case .success(let item):
                      onDrop(item, targetIndex)
                  case .failure(let error):
                      print("❌ Drop failed: \(error)")
                  }
                  onUpdateTarget(nil)
              }
          }
          return true
      }

      // 위치 기반 타겟 인덱스 계산
      private func updateTargetIndex(for location: CGPoint) {
          let isTopHalf = location.y < rowHeight / 2
          let targetIndex = isTopHalf ? index : index + 1
          onUpdateTarget(targetIndex)
      }
  }

위와 같이 info.location.y 값을 통해 드래그 위치가 ItemRow의 상단 절반인지 하단 절반인지 판별하여 targetIndex를 계산합니다.

이 방식을 통해 사용자가 ItemRow의 어느 위치에 드롭하더라도 의도에 맞는 위치에 아이템을 삽입할 수 있게 되었습니다.

1.3. onDrop 적용

이렇게 구현한 ItemDropDelegate를 드롭 동작을 listen해야하는 뷰에 onDrop 뷰수정자와 함께 체이닝시켜줍니다.

.onDrop(
      of: [.data],
      delegate: ItemDropDelegate<Item>(
          index: index,
          rowHeight: rowHeight,
          onUpdateTarget: { newIndex in
              targetedDropIndex = newIndex
          },
          onDrop: { droppedItem, targetIndex in
              moveItem(droppedItem, to: targetIndex)
          }
      )
  )

2. UX 고도화

2.1. 터치 피드백 추가

dropDestination을 사용할 때는 draggable 수정자가 적용된 뷰에 터치 시 기본 피드백이 제공되지 않았습니다. 이를 해결하기 위해 ItemRow를
Button으로 감싸 시스템의 기본 터치 피드백을 활용했습니다.

// Button으로 감싸서 터치 피드백 제공
  Button(action: {}) {
      itemContent(item, false)
  }
  .draggable(item) {
      // 드래그 프리뷰
      itemContent(item, true)
          .frame(height: rowHeight)
  }

Button의 기본 동작으로 터치 시 약간의 opacity 변화가 발생하여, 사용자가 터치가 인식되고 있음을 즉시 인지할 수 있게 되었습니다.

2.2. 순서 변경 시 햅틱 피드백

드래그 중 삽입 위치가 변경될 때마다 촉각 피드백을 제공하여, 사용자가 현재 어느 위치에 아이템이 삽입될지 직관적으로 파악할 수 있도록 했습니다.

 .onChange(of: targetedDropIndex) { oldValue, newValue in
      // targetIndex가 실제로 변경되었을 때만 햅틱 피드백 발생
      if oldValue != newValue, newValue != nil {
          let generator = UIImpactFeedbackGenerator(style: .light)
          generator.impactOccurred()
      }
  }

2.3 삽입 위치 Indicator 애니메이션

드래그 중 삽입될 위치를 시각적으로 표시하기 위해 Indicator를 추가하고, 위치 변경 시 부드러운 애니메이션을 적용했습니다.

VStack(spacing: 0) {
      // 상단 Indicator - 현재 아이템 위에 삽입될 때 표시
      if targetedDropIndex == index {
          RoundedRectangle(cornerRadius: 2)
              .fill(Color.blue.opacity(0.3))
              .frame(maxWidth: .infinity, maxHeight: .infinity)
              .padding(.horizontal, 16)
      }

      Button(action: {}) {
          itemContent(item, false)
      }

      // 하단 Indicator - 현재 아이템 아래에 삽입될 때 표시
      if targetedDropIndex == index + 1 {
          RoundedRectangle(cornerRadius: 2)
              .fill(Color.blue.opacity(0.3))
              .frame(maxWidth: .infinity, maxHeight: .infinity)
              .padding(.horizontal, 16)
      }
  }

3. 재사용성 향상

3.1 Generic Protocol 정의

다양한 타입의 아이템에서 DraggableList를 사용할 수 있도록 Draggable 프로토콜을 정의했습니다.

protocol Draggable: Identifiable, Codable, Equatable, Transferable {
      var id: UUID { get }
  }
//  - Identifiable: ForEach에서 아이템 식별
//  - Codable: Transferable 구현을 위한 직렬화
//  - Equatable: 아이템 비교 및 변경 감지
//  - Transferable: 시스템 드래그 앤 드롭 지원

3.2 ViewBuilder를 통한 Row 동적 주입

struct DraggableList<Item: Draggable, ItemRow: View>: View {
    // ...
    let itemContent: (Item, Bool) -> ItemRow

    init(
        // ...
        @ViewBuilder itemContent: @escaping (Item, Bool) -> ItemRow
    ) {
        self.itemContent = itemContent
    }
}

@ViewBuilder를 사용하여 호출부에서 자유롭게 Row 뷰를 정의할 수 있도록 설계했습니다. 여기서 두 번째 파라미터 Bool은 드래그 중인지 여부를 나타내어, 드래그 프리뷰와 일반 상태를 구분할 수 있도록 했습니다.\

 // 사용 예시
  DraggableList(
      items: $items,
      rowHeight: 72
  ) { item, isDragging in
      HStack {
          Text(item.title)
          Spacer()
          Image(systemName: "line.3.horizontal")
      }
      .opacity(isDragging ? 0.8 : 1.0)
  }

3.3 콜백을 통한 확장성

마지막으로 외부에서 처리할 수 있도록 재정렬 이벤트를 주입받도록 했습니다.

var onReorder: ((_ from: Int, _ to: Int) -> Void)?

이를 통해 서버 동기화, 로깅, 추가 비즈니스 로직 등을 DraggableList 외부에서 처리할 수 있습니다.

전체 코드

import SwiftUI
import CoreTransferable
internal import UniformTypeIdentifiers

/// DraggableList에서 사용할 아이템 프로토콜
/// Transferable을 준수해야 시스템 드래그 앤 드롭 사용 가능
protocol Draggable: Identifiable, Codable, Equatable, Transferable {
    var id: Int { get }
}

// MARK: - ItemDropDelegate
/// 드래그 위치를 실시간으로 트래킹하기 위한 DropDelegate
struct ItemDropDelegate<Item: Draggable>: DropDelegate {
    let index: Int
    let rowHeight: CGFloat
    let onUpdateTarget: (Int?) -> Void
    let onDrop: (Item, Int) -> Void

    func dropEntered(info: DropInfo) {
        updateTargetIndex(for: info.location)
    }

    func dropUpdated(info: DropInfo) -> DropProposal? {
        updateTargetIndex(for: info.location)
        return DropProposal(operation: .move)
    }

    func dropExited(info: DropInfo) {
        onUpdateTarget(nil)
    }

    func performDrop(info: DropInfo) -> Bool {
        let isTopHalf = info.location.y < rowHeight / 2
        let targetIndex = isTopHalf ? index : index + 1

        guard let itemProvider = info.itemProviders(for: [.data]).first else {
            onUpdateTarget(nil)
            return false
        }

        _ = itemProvider.loadTransferable(type: Item.self) { result in
            DispatchQueue.main.async {
                switch result {
                case .success(let item):
                    onDrop(item, targetIndex)
                case .failure(let error):
                    print("❌ Drop failed: \(error)")
                }
                onUpdateTarget(nil)
            }
        }

        return true
    }

    private func updateTargetIndex(for location: CGPoint) {
        let isTopHalf = location.y < rowHeight / 2
        let targetIndex = isTopHalf ? index : index + 1
        onUpdateTarget(targetIndex)
    }
}

// MARK: - DraggableList

struct DraggableScrollView<Item: Draggable, ItemRow: View, Header: View, Footer: View>: View {
    // MARK: - Properties
    @Binding var items: [Item]

    /// 각 행의 고정 높이
    let rowHeight: CGFloat
    let isDragEnabled: Bool

    /// 아이템 재정렬 콜백
    var onReorder: (() -> Void)?
    
    /// 각 행의 뷰를 생성하는 클로저
    let itemContent: (Item, Bool) -> ItemRow
    let onTapRow: (Item) -> Void

    /// Header/Footer 뷰
    let header: Header
    let footer: Footer

    // MARK: - State
    /// 현재 드롭 타겟 인덱스
    @State private var targetedDropIndex: Int?
    /// iOS 16 호환: onChange에서 oldValue 비교를 위한 이전 값 저장
    @State private var prevTargetedDropIndex: Int?

    // MARK: - Initializer
    init(
        items: Binding<[Item]>,
        rowHeight: CGFloat = 60,
        isDragEnabled: Bool,
        onReorder: (() -> Void)? = nil,
        onTapRow: @escaping (Item) -> Void,
        @ViewBuilder itemContent: @escaping (Item, Bool) -> ItemRow,
        @ViewBuilder header: () -> Header,
        @ViewBuilder footer: () -> Footer
    ) {
        self._items = items
        self.rowHeight = rowHeight
        self.isDragEnabled = isDragEnabled
        self.onReorder = onReorder
        self.onTapRow = onTapRow
        self.header = header()
        self.footer = footer()
        self.itemContent = itemContent
    }
    
    var body: some View {
        ScrollView {
            header
            LazyVStack(spacing: 0) {
                ForEach(Array(items.enumerated()), id: \.element.id) { index, item in
                    itemRowView(index: index, item: item)
                }
            }
            footer
        }
        .animation(.spring(response: 0.3, dampingFraction: 0.7), value: targetedDropIndex)
        .animation(.spring(response: 0.3, dampingFraction: 0.7), value: items)
        .onChange(of: targetedDropIndex) { newValue in
            if prevTargetedDropIndex != newValue, newValue != nil {
                let generator = UIImpactFeedbackGenerator(style: .light)
                generator.impactOccurred()
            }
            prevTargetedDropIndex = newValue
        }
    }

    private func itemRowView(index: Int, item: Item) -> some View {
        VStack(spacing: 0) {
            if targetedDropIndex == index {
                UnevenRoundedRectangle(
                    topLeadingRadius: index == 0 ? 4 : 0,
                    bottomLeadingRadius: 4,
                    bottomTrailingRadius: 4,
                    topTrailingRadius: index == 0 ? 4 : 0
                )
                .fill(.blue)
                .frame(maxWidth: .infinity, maxHeight: .infinity)
                .padding(.horizontal, 16)
            }
            
            Button(action: { onTapRow(item) }) {
                itemContent(item, false)
            }
            
            if targetedDropIndex == index + 1 {
                UnevenRoundedRectangle(
                    topLeadingRadius: 4,
                    bottomLeadingRadius: index == items.count - 1 ? 4 : 0,
                    bottomTrailingRadius: index == items.count - 1 ? 4 : 0,
                    topTrailingRadius: 4
                )
                .fill(.blue)
                .frame(maxWidth: .infinity, maxHeight: .infinity)
                .padding(.horizontal, 16)
            }
        }
        .frame(height: rowHeight + 16)
        .disabled(!isDragEnabled)
        .draggable(item) {
            itemContent(item, true)
                .frame(height: rowHeight)
        }
        .id(item.id)
        .onDrop(
            of: [.data],
            delegate: ItemDropDelegate<Item>(
                index: index,
                rowHeight: rowHeight,
                onUpdateTarget: { newIndex in
                    targetedDropIndex = newIndex
                },
                onDrop: { droppedItem, targetIndex in
                    moveItem(droppedItem, to: targetIndex)
                }
            )
        )
    }
    
    // MARK: - Move Logic
    private func moveItem(_ item: Item, to targetIndex: Int) {
        guard let currentIndex = items.firstIndex(where: { $0.id == item.id }) else {
            print("❌ Item not found in array")
            return
        }
        guard currentIndex != targetIndex else {
            print("❌ Same position, no move needed")
            return
        }
        /// targetIndex `뒤로` item이 이동되어야 합니다.
        let movedItem = items.remove(at: currentIndex)
        let insertIndex = targetIndex > currentIndex ? targetIndex - 1 : targetIndex
        items.insert(movedItem, at: insertIndex)
        onReorder?()
    }
}

// MARK: - Convenience Initializers

extension DraggableScrollView where Header == EmptyView, Footer == EmptyView {
    /// Header, Footer 없이 사용하는 경우
    init(
        items: Binding<[Item]>,
        rowHeight: CGFloat = 60,
        isDragEnabled: Bool,
        onReorder: (() -> Void)? = nil,
        onTapRow: @escaping (Item) -> Void,
        @ViewBuilder itemContent: @escaping (Item, Bool) -> ItemRow
    ) {
        self.init(
            items: items,
            rowHeight: rowHeight,
            isDragEnabled: isDragEnabled,
            onReorder: onReorder,
            onTapRow: onTapRow,
            itemContent: itemContent,
            header: { EmptyView() },
            footer: { EmptyView() }
        )
    }
}

extension DraggableScrollView where Footer == EmptyView {
    /// Header만 사용하는 경우
    init(
        items: Binding<[Item]>,
        rowHeight: CGFloat = 60,
        isDragEnabled: Bool,
        onReorder: (() -> Void)? = nil,
        onTapRow: @escaping (Item) -> Void,
        @ViewBuilder itemContent: @escaping (Item, Bool) -> ItemRow,
        @ViewBuilder header: () -> Header
    ) {
        self.init(
            items: items,
            rowHeight: rowHeight,
            isDragEnabled: isDragEnabled,
            onReorder: onReorder,
            onTapRow: onTapRow,
            itemContent: itemContent,
            header: header,
            footer: { EmptyView() }
        )
    }
}

extension DraggableScrollView where Header == EmptyView {
    /// Footer만 사용하는 경우
    init(
        items: Binding<[Item]>,
        rowHeight: CGFloat = 60,
        isDragEnabled: Bool,
        onReorder: (() -> Void)? = nil,
        onTapRow: @escaping (Item) -> Void,
        @ViewBuilder itemContent: @escaping (Item, Bool) -> ItemRow,
        @ViewBuilder footer: () -> Footer
    ) {
        self.init(
            items: items,
            rowHeight: rowHeight,
            isDragEnabled: isDragEnabled,
            onReorder: onReorder,
            onTapRow: onTapRow,
            itemContent: itemContent,
            header: { EmptyView() },
            footer: footer
        )
    }
}

4. 결론

dropDestination은 간단한 드래그 앤 드롭 구현에 적합하지만, 세밀한 위치 추적이 필요한 경우에는 DropDelegate를 사용하는 것이 적합합니다. DropDelegate를 통해 드래그 위치를 실시간으로 추적하고, 이를 기반으로 더 직관적인 사용자 경험을 제공할 수 있었습니다.

특히 햅틱 피드백과 시각적 Indicator의 조합은 사용자가 드래그 중 현재 상태를 명확하게 인지할 수 있게 해주어, 전체적인 인터랙션 품질을 크게 향상시켰습니다.

감사합니다.

0. 구현 배경

초기에는 밑으로 이동 버튼 표시 여부 판단을 위해 Scroll 위치를 파악하고자, 리스트 아이템 내부에 onAppear 콜백이 체이닝된 Spacer()를 삽입한 후, 이를 통해 버튼 표시 여부를 트리거하고자 했습니다.

하지만, 2가지 한계점이 존재했습니다.

1번째로 표시 및 미표시 2개 이벤트에 대한 시점을 모두 제어하기에는 불충분했습니다.

또한, 2번째로 메시지 간 개행이 삽입되어 아이템 간 높이값에 큰 폭의 차이가 존재할경우, 일관되지 않은 사용자 경험을 제공해 사용자에게 혼란을 줄 수 있었습니다.

이를 해결하기 위해 가장 먼저 구현이 필요한 기능들을 아래와 같이 정리했습니다.

1. 구현 조건 정의

최하단으로 이동 플로팅 버튼

• ScrollView를 고정된 거리만큼 위로 스크롤하면, 버튼을 우측 하단에 표시
• 반대로 ScrollView의 최하단으로부터 거리가 가까워질 경우, 버튼을 hide

상단 페이지네이션

• 최상단으로 스크롤 시, 자연스럽게 위 방향으로 새로운 Item들이 fetch

2. 상단 페이지네이션

상단 페이지네이션이 자연스럽게 수행되기 위해선, 아래 2 조건이 충족되어야 합니다.

• 리스트 내부 아이템이 추가될때, 현재 리스트의 offset이 변경되지 않고, 자연스럽게 상단에 추가
• 스크롤 위치만으로 아이템 추가를 위한 fetch 작업 트리거

리스트의 offset 변경 없이, Item이 추가되는 방법은 아래 블로그에서 굉장히 세부적으로 다루고 있어, 많이 도움이 되었습니다.

https://dokit.tistory.com/65#google_vignette

이를 참고하여 scaleEffect(y: -1)를 ScrollView에 1번, 내부 Item에 선언하여 ScrollView 자체를 상하단으로 뒤집어 현재 사용자가 보고있는 Item들을 화면에 유지하며 자연스럽게 상단에 새로운 Item이 추가되게끔 설계할 수 있었습니다.

import SwiftUI

struct ContentView: View {
    struct Message: Hashable {
        let id: UUID = .init()
        let text: String
    }
    
    @State var messages: [Message] = (0..<50).map { Message(text: String($0)) }

    var body: some View {
        CustomScrollView { proxy in
            LazyVStack(spacing: 0) {
                ForEach(messages, id: \.self) { message in
                    Text("\(message.text)")
                        .frame(maxWidth: .infinity)
                        .frame(height: 48, alignment: .center)
                        .id(message.id)
                        // 2. 상하단으로 뒤집어보이지 않게 내부적으로 한번 더 호출
                        .scaleEffect(y: -1)
                }
            }
            .background(.gray)
        }
    }
}

struct CustomScrollView<Content: View, Overlay: View>: View {
    @ViewBuilder var content: (ScrollViewProxy) -> Content
    var body: some View {
        ScrollViewReader { scrollProxy in
            ScrollView(.vertical, showsIndicators: true) {
                content(scrollProxy)
            }
            // 1. ScrollView 자체를 상하단으로 뒤집기
            .scaleEffect(y: -1)
        }
    }
}

여기서 각 Item마다 명시적 정체성을 부여하는 이유는 scaleEffect 처리를 하게 될 경우, SwiftUI에서 상태 변화를 트래킹하는 데에 있어 기존 뷰가 뒤집힌 것인지 vs 데이터 자체에 변동이 있었는지 혼동할 때가 있기 때문입니다.

때문에 데이터 업데이트 시, 이전의 데이터와 같음을 즉각적으로 전달시켜 불필요한 레이아웃 재계산을 줄이고 화면이 깜빡이는 glitch 현상을 억제하고자 했습니다.

3. 스크롤 offset값 실시간 추적

플로팅버튼의 정확한 표시 시점을 추적하기 위해선, 스크롤 컨텐츠 내부에서 사용자가 현재 스크롤하고 있는 절대적인 offset 값을 접근해야 했습니다.

이를 구현하기 위해 GeometryReader와 자식 뷰에서 부모뷰로 데이터를 전달할 수 있는 PreferenceKey를 사용하였습니다.

GeometryReader 는 상위 View가 제안한 위치, 크기에 대한 정보에 접근할 수 있도록 돕는 도구입니다.

최상단 y 좌표값과 전체 높이값을 파악하기 위해 제안받은 공간을 CGRect 타입으로 반환하는 .frame() 메서드를 사용했습니다.

frame() 메서드 사용 시에는 CoordinateSpace 인자를 요구하는데, 이는 아래와 같습니다.

• .global: 스크린 전체에 대한 좌표 공간을 반환
• .local: GeometryReader의 좌표 공간을 반환
• .named : .coordinateSpace(name: ${식별자 String})을 호출한 뷰의 좌표 공간을 반환

스크롤 가능한 전체 콘텐츠에 대한 offset이 필요했기 때문에, 이와 동일한 공간을 차지할 수 있게끔 .background() 수정자와 함께 GeometryReader로 래핑한 투명 영역을 추가하였으며, ScrollView 자체에 대해 .coordinateSpace 수정자를 체이닝하여 해당 영역에 대한 공간을 접근하고자 했습니다.

import SwiftUI

struct CustomScrollView<Content: View, Overlay: View>: View {
    @ViewBuilder var content: (ScrollViewProxy) -> Content
    
    @Namespace private var coordinateSpaceName: Namespace.ID
    
    var body: some View {
        ScrollViewReader { scrollProxy in
            ScrollView(.vertical, showsIndicators: true) {
                content(scrollProxy)
                    .background {
                        GeometryReader { scrollContentProxy in
                            Color.clear
                        }
                    }
            }
            .scaleEffect(y: -1)
            // .frame() 메서드로 ScrollView에 대한 좌표공간 조회 위해 추가
            .coordinateSpace(name: coordinateSpaceName)
        }
    }
}

이후 각 CoordinateSpace의 차이를 상세히 파악하고자,

1. 최상단으로 스크롤하였을 때,
2. ScrollView 내부 컨텐츠가 스크린 상단에 걸쳐있을때,
3. 최하단으로 스크롤하였을때

3가지 경우에 대해 3가지 coordinateSpace에 대한 CGRect를 모두 로그로 출력해보았습니다.

1. 최상단으로 스크롤하였을 때

ScrollView에 대한 좌표 공간의 경우, minY 즉, 좌표의 최상단 좌측 y좌표가 0을 가르키고 있는 반면, global 좌표 공간은 62를 가리키고 있는데요. 이는 전체 스크린 영역에 SafeAreaPadding을 같이 포함시키고 있기 때문입니다.

그 외에, minX, width, height 값은 모두 동일합니다.

2. ScrollView 내부 컨텐츠가 스크린 상단에 걸쳐있을때

스크롤 뷰를 SafeAreaPadding을 넘어 스크린 최상단까지 스크롤할 경우, ScrollView 좌표공간 기준으로는 원래 위치보다 더 SafeAreaPadding만큼 위로 올라갔기 때문에 -62를 가리키는 반면, global 좌표공간은 0을 가르키고 있는 것을 확인할 수 있습니다.

3. 최하단으로 스크롤하였을 때

스크롤을 끝까지 아래로 내렸음에도 불구하고 scrollView와 global 기준 모두 minY가 height와 동일해지지 않았는데요. 그 이유는 minY의 기준점 자체가 컨테이너의 상단점이기 때문에, height만큼 스크롤하려면 가장 하단에 있는 Item 즉 “0” Item이 화면 상단까지 이동되어야 하기 때문입니다. 이는 일반적인 ScrollView에서는 사용자로부터 기대되는 구현방향이 아닙니다. 때문에, 여기에 ScrollView를 품고 있는 부모뷰 자체의 고정 높이값을 충당하여 +-0 이되게끔 연산이 필요합니다.

import SwiftUI

struct CustomScrollView<Content: View, Overlay: View>: View {
    @ViewBuilder var content: (ScrollViewProxy) -> Content
    
    @Namespace private var coordinateSpaceName: Namespace.ID
    
    var body: some View {
        GeometryReader { containerProxy in // 최상단에 GeometryReader 추가
            ScrollViewReader { scrollProxy in
                ScrollView(.vertical, showsIndicators: true) {
                    content(scrollProxy)
                        .background {
                            GeometryReader { scrollContentProxy in
                                Color.clear
                            }
                        }
                }
                .scaleEffect(y: -1)
                .coordinateSpace(name: coordinateSpaceName)
            }
        }
    }
}

Scroll offset을 실시간으로 추적하면서 얻을 수 있는 값은 아래와 같습니다.

최하단까지의거리: content(scrollProxy) 높이값 - (스크롤 offset + 컨테이너의 고정높이)

최상단까지의거리: 스크롤 offset

이를 PreferenceKey를 통해 content()에서 수집한후, 변화를 추적하도록 하였습니다. PreferenceKey에 대한 설명은 상단에 첨부한 블로그에서도 상세히 다루고 있습니다 :)

import SwiftUI

struct VerticalDistanceKey: PreferenceKey {
    static var defaultValue: [CGFloat] = []
    static func reduce(value: inout [CGFloat], nextValue: () -> [CGFloat]) {}
}

struct CustomScrollView<Content: View, Overlay: View>: View {
    @Binding var distance: (toTop: CGFloat, toBottom: CGFloat)
    @ViewBuilder var content: (ScrollViewProxy) -> Content
    @Namespace private var coordinateSpaceName: Namespace.ID
    
    var body: some View {
        GeometryReader { containerProxy in // 최상단에 GeometryReader 추가
            ScrollViewReader { scrollProxy in
                ScrollView(.vertical, showsIndicators: true) {
                    content(scrollProxy)
                        .background {
                            GeometryReader { scrollContentProxy in
                                Color.clear
                                    .preference(
                                        key: VerticalDistanceKey.self,
                                        value: [
                                            -scrollContentProxy.frame(in: .named(coordinateSpaceName)).minY,
                                             scrollContentProxy.frame(in: .named(coordinateSpaceName)).height -
                                             (
                                                -scrollContentProxy.frame(in: .named(coordinateSpaceName)).minY +
                                                 containerProxy.size.height
                                             )
                                        ]
                                    )
                            }
                        }
                }
                .scaleEffect(y: -1)
                .coordinateSpace(name: coordinateSpaceName)
                .onPreferenceChange(VerticalDistanceKey.self) { verticalDistance in
                     distance = (toTop : verticalDistance[0], toBottom: verticalDistance[1])
                 }
            }
        }
    }
}

이로써, 이제 CustomScrollView의 부모뷰는 전달받은 verticalDistance 튜플을 통해 offset 변화에 따른 UI 변화, 예를 들어 플로팅버튼 표시나 상단 페이지네이션 트리거가 가능해집니다.

struct ContentView: View {
    struct Message: Hashable {
        let id: UUID = .init()
        let text: String
    }
    
    @State var verticalDistance: (toTop: CGFloat, toBottom: CGFloat) = (.zero, .zero)
    @State var messages: [Message] = (0..<50).map { Message(text: String($0)) }
    
    func addMore() async {
        DispatchQueue.main.async {
            if let lastMessage = messages.last?.text {
                let newMessages = (Int(lastMessage)!...Int(lastMessage)!+30).map { i in
                    Message(text: String(i))
                }
                messages.append(contentsOf: newMessages)
            }
        }
    }
    
    var body: some View {
        ZStack {
            CustomScrollView(distance: $verticalDistance) { proxy in
                LazyVStack(spacing: 0) {
                    ForEach(messages, id: \.self) { message in
                        Text("\(message.text)")
                            .frame(maxWidth: .infinity)
                            .frame(height: 48, alignment: .center)
                            .id(message.id)
                            .scaleEffect(y: -1)
                    }
                }
                .background(.gray)
            }
            // 상단으로부터의 거리가 100보다 줄어들 경우, 상단 페이지네이션 수행
            .onChange(of: verticalDistance.toTop) { dist in
                if dist < 100 {
                    Task {
                        await addMore()
                    }
                }
            }
            // 하단으로부터의 거리가 100보다 줄어들 경우, 밑으로 이동 버튼 표시
            if verticalDistance.toBottom < 100 {
                Button(action: {
                    withAnimation {
                        // first로 한 이유는 scaleEffect(y:-1)로 인해 메시지 순서가 보이는 것과 반대이기 때문입니다.
                        if let lastId = messages.first?.id {
                            proxy.scrollTo(lastId, anchor: .bottom)
                        }
                    }
                }) {
                    Image(systemName: "chevron.down")
                        .renderingMode(.template)
                        .foregroundStyle(.gray)
                        .frame(width: 48, height: 48, alignment: .center)
                        .background(.white, in: Circle())
                        .shadow(color: .black.opacity(0.08), radius: 4, x: 0, y: 2)
                }
                .padding(16)
                .transition(.move(edge: .bottom).combined(with: .opacity))
                .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .bottomTrailing)
            }
        }
        .animation(.spring, value: verticalDistance.toBottom > 100)
    }
}

하지만, 하단에 보이는 플로팅 버튼은 클릭 시 스크롤 제어를 할 수 있어야 하기에 ScrollProxy에 대한 접근이 필요합니다.

import SwiftUI

struct VerticalDistanceKey: PreferenceKey {
    static var defaultValue: [CGFloat] = []
    static func reduce(value: inout [CGFloat], nextValue: () -> [CGFloat]) {}
}

struct CustomScrollView<Content: View, Overlay: View>: View {
    @Binding var distance: (toTop: CGFloat, toBottom: CGFloat)
    var content: (ScrollViewProxy) -> Content
    var overlayContent: ((ScrollViewProxy) -> Overlay)?
    
    init(
        distance: Binding<(toTop: CGFloat, toBottom: CGFloat)>,
        @ViewBuilder content: @escaping (ScrollViewProxy) -> Content,
        @ViewBuilder overlayContent: @escaping (ScrollViewProxy) -> Overlay = { _ in EmptyView() }
    ) {
        self._distance = distance
        self.content = content
        self.overlayContent = overlayContent
    }
    
    @Namespace private var coordinateSpaceName: Namespace.ID
    
    var body: some View {
        GeometryReader { containerProxy in
            ScrollViewReader { scrollProxy in
                ZStack {
                    ScrollView(.vertical, showsIndicators: true) {
                        content(scrollProxy)
                            .background {
                                GeometryReader { scrollContentProxy in
                                    Color.clear
                                        .preference(
                                            key: VerticalDistanceKey.self,
                                            value: [
                                                -scrollContentProxy.frame(in: .named(coordinateSpaceName)).minY,
                                                 scrollContentProxy.frame(in: .named(coordinateSpaceName)).height -
                                                 (
                                                    -scrollContentProxy.frame(in: .named(coordinateSpaceName)).minY +
                                                     containerProxy.size.height
                                                 )
                                            ]
                                        )
                                }
                            }
                    }
                    .scaleEffect(y: -1)
                    .coordinateSpace(name: coordinateSpaceName)
                    .onPreferenceChange(VerticalDistanceKey.self) { verticalDistance in
                        distance = (toTop : verticalDistance[0], toBottom: verticalDistance[1])
                    }
                    overlayContent?(scrollProxy)
                }
            }
        }
    }
}

때문에, CustomScrollView 내부에 proxy에 대한 접근이 가능한 overlayContent를 인자로 받을 수 있게끔 설계해, 범용성을 높였습니다.

struct ContentView: View {
    struct Message: Hashable {
        let id: UUID = .init()
        let text: String
    }
    
    @State var verticalDistance: (toTop: CGFloat, toBottom: CGFloat) = (.zero, .zero)
    @State var messages: [Message] = (0..<50).map { Message(text: String($0)) }
    
    func addMore() async {
        DispatchQueue.main.async {
            if let lastMessage = messages.last?.text {
                let newMessages = (Int(lastMessage)!...Int(lastMessage)!+30).map { i in
                    Message(text: String(i))
                }
                messages.append(contentsOf: newMessages)
            }
        }
    }
    
    var body: some View {
        CustomScrollView(distance: $verticalDistance) { proxy in
            LazyVStack(spacing: 0) {
                ForEach(messages, id: \.self) { message in
                    Text("\(message.text)")
                        .frame(maxWidth: .infinity)
                        .frame(height: 48, alignment: .center)
                        .id(message.id)
                        .scaleEffect(y: -1)
                }
            }
            .background(.gray)
        } overlayContent: { proxy in
            if verticalDistance.toBottom > 100 {
                Button(action: {
                    withAnimation {
                        if let lastId = messages.first?.id {
                            proxy.scrollTo(lastId, anchor: .bottom)
                        }
                    }
                }) {
                    Image(systemName: "chevron.down")
                        .renderingMode(.template)
                        .foregroundStyle(.gray)
                        .frame(width: 48, height: 48, alignment: .center)
                        .background(.white, in: Circle())
                        .shadow(color: .black.opacity(0.08), radius: 4, x: 0, y: 2)
                }
                .padding(16)
                .transition(.move(edge: .bottom).combined(with: .opacity))
                .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .bottomTrailing)
            }
        }
        .animation(.spring, value: verticalDistance.toBottom > 100)
        .onChange(of: verticalDistance.toTop) { dist in
            if dist < 100 {
                Task {
                    await addMore()
                }
            }
        }
    }
}

4. 주의점

상단 페이지네이션에 호출되는 fetch작업은 일반적으로 비동기적으로 수행됩니다.

때문에 로딩도중에도 fetch를 반복적으로 연속 트리거할 수 있습니다. 때문에 isLoading 플래그를 통해 불필요한 api 호출을 막아 이를 예방해야합니다.

감사합니다.

0. 구현 배경

초기에는 Material3가 제공하는 ModalBottomSheet를 사용하여 바텀시트를 구현하였습니다. 하지만, 내부에 자체 구현한 피커를 사용할 때 피커 조작이 dragDismiss 동작으로 넘어가는 이슈가 있었습니다.

자체 구현 피커 관련 블로그 링크

https://medium.com/@neoself1105/jetpack-compose%EB%A1%9C-wheelpicker-%EA%B5%AC%ED%98%84%ED%95%98%EA%B8%B0-92b95600eeb4

0.1. confirmValueChange를 통한 1차 해결 시도

아래 스택오버플로우 답변을 참고하여 material3에서 제공하는 bottomSheetState 내부 confirmValueChange를 통해 드래그 동작을 통해 바텀시트가 내려가는 이슈를 해결하려 하였으나, 바텀시트가 내려가지는 않지만 드래그 동작이 바텀시트 드래그로 넘어가 피커가 동작되지 않는 이슈가 여전히 존재했습니다.

How to disable Drag behaviour on ModalBottomSheet , android compose

0.2. Compose 버전 업데이트를 통한 2차 해결

material3의 1.4.0 버전부터는 ModalBottomSheet에 SheetGestureEnabled 인자가 추가되었으며, 해당 인자값을 통해 드래그 동작 자체가 수행되지 않도록 제어가 가능해졌습니다.

하지만, 바텀시트가 표시된 상태에서 네비게이션 바의 뒤로가기 버튼으로 바텀시트를 닫은 후, 다시 동일한 바텀시트를 표시하려 하면 바텀시트가 올라오지 않는 현상이 발생했습니다.

이 문제의 원인은 바텀시트 제어 로직의 데이터 일관성 문제에 있었습니다. 선언형 UI 패턴에서 바텀시트를 제어하기 위해 isPresent 불린 상태값을 사용했는데, 내비게이션 바 뒤로가기 시 onDismissRequest 콜백이 호출되지 않는 버그로 인해 isPresent가 false로 변경되지 않았습니다.

// 기존 문제가 있던 구조
@Composable
fun CustomBottomSheet(
  isPresent: Boolean,  // 외부에서 주입받는 상태
  onDismiss: () -> Unit,
  ...
) {
  if (internalVisible) {
    ModalBottomSheet(
      onDismissRequest = { /* 시스템 뒤로가기 버튼 클릭 시 호출되지 않음! */ },
      ...
    )
  }
}

결과적으로 isPresent가 여전히 true인 상태에서 동일한 바텀시트 표시를 시도하면, 상태 변화가 없으므로 아무 동작도수행되지 않았습니다. 이러한 이유로 ModalBottomSheet를 대체할 커스텀 바텀시트를 직접 구현하게 되었습니다.

1. 구현 목표

위 이유로 인해 ModalBottomSheet를 대체할 수 있는 커스텀 바텀시트를 직접 구현하는 판단을 내리게 되었습니다.

구현하기에 앞서iOS SwiftUI의 기본 BottomSheet와 동일한 사용자 경험을 제공하기 위해 다음 요구사항을 정의했습니다:

1. 바텀시트 상단영역만 드래그가 동작
2. 바텀시트의 열림, 닫힘, 드래그 후 Settling 동작에 Spring 애니메이션을 적용
3. 바텀시트를 최대 높이보다 위로 더 드래그할 경우, 드래그 거리에 0.3의 저항 계수를 적용하여 손가락 이동 거리의 30%만 바텀시트가 이동
4. Fling 감지: 아래쪽으로 빠르게 튕기듯이 드래그하면 즉시 hide로 변경
5. 위치 기반: 드래그가 느릴 경우, 바텀시트 높이의 50% 이상 아래로 내렸을 때만 닫히며, 그보다 덜 내리면 다시 원래 위치로 복구
6. onOutTapDismissEnabled = true일경우, 바텀시트 외부 영역(Scrim)을 터치하면 바텀시트가 hide로 변경
7. 어두운 영역(Scrim)은 바텀시트가 노출된 정도(0.0~1.0)에 따라 투명도가 0% ~ 40% 사이에서 실시간으로 변경

2. 아키텍처 설계: 3계층 구조

그 다음, 커스텀 바텀시트를 구현하기 위해 3계층 구조를 설계했습니다:

이 구조의 핵심은 CustomBottomSheetController가 Single Source of Truth(SSoT) 역할을 수행한다는 점입니다.

3. CustomBottomSheetController: 통합된 상태 관리자

// 전체 코드
@Stable
class CustomBottomSheetController(val scope: CoroutineScope) {
    // ==================== 애니메이션 상태 ====================
    var status by mutableStateOf(SheetStatus.HIDDEN)
        private set
    // 애니메이션 진행 도중 연속 트리거 시 발생되는 상태 불일치 문제를 해결을 위해 애니메이션 도중 세우는 플래그입니다.
    var isAnimating by mutableStateOf(false)
        private set
    // 바텀시트가 완전히 펼쳐진 상태(EXPANDED)를 기준으로 얼마나 아래로 내려가 있는지(이동했는지)를 나타내는 값
    val offsetY = Animatable(0f)
    var sheetHeightPx by mutableFloatStateOf(0f)
        private set
    // 바텀시트 높이값 수정을 담당하는 이벤트입니다.
    var onSlide: ((Float) -> Unit)? = null
    // 실제 바텀시트 state를 0.0(hidden)에서 1.0(expanded) 사이의 수치로 치환한 값입니다.
    val progress: Float
        get() {
            if (sheetHeightPx == 0f) return 0f
            return 1f - (offsetY.value / sheetHeightPx).coerceIn(0f, 1f)
        }
    // ==================== 바텀시트 속성 (기존 CustomBottomSheetNavigator) ====================
    var content by mutableStateOf<@Composable () -> Unit>({})
        private set
    var height by mutableStateOf(280.dp)
        private set
    private var onDismissCallback: (() -> Unit)? = null
    private var onTapBackNavBtnCallback: (() -> Unit)? = null
    var onTapScrimDismissEnabled by mutableStateOf(true)
        private set
    var onDragDismissEnabled by mutableStateOf(true)
        private set
    // ==================== 애니메이션 메서드 ====================
    // Initialize state - 바텀시트 높이 업데이트
    // 주의: 애니메이션 진행 중에는 snapTo()를 호출하지 않습니다. snapTo()가 animateTo()를 취소시키기 때문입니다.
    internal fun updateSheetHeight(heightPx: Float) {
        if (this.sheetHeightPx != heightPx) {
            this.sheetHeightPx = heightPx
            // 애니메이션 중이면 높이만 업데이트하고 offset 조정은 스킵
            if (isAnimating) return
            // 만일 HIDDEN 상태이면, offset을 강제로 조정합니다.
            if (status == SheetStatus.HIDDEN) {
                scope.launch {
                    offsetY.snapTo(heightPx)
                }
            } else if (status == SheetStatus.EXPANDED) {
                scope.launch {
                    offsetY.snapTo(0f)
                }
            }
        } else {
            // 애니메이션 중이면 스킵
            if (isAnimating) return
            // 만일 status가 HIDDEN인데 offset가 height와 불일치할 경우는 offset을 강제로 heightPx에 맞춥니다.
            if (status == SheetStatus.HIDDEN && offsetY.value != heightPx) {
                scope.launch { offsetY.snapTo(heightPx) }
            }
        }
    }
    internal suspend fun animateTo(target: SheetStatus) {
        // 애니메이션 진행 중이면 무시
        if (isAnimating) return
        val targetOffset = when (target) {
            SheetStatus.EXPANDED -> 0f
            SheetStatus.HIDDEN -> sheetHeightPx
        }
        isAnimating = true
        try {
            if (target == SheetStatus.EXPANDED) {
                status = target
            }
            offsetY.animateTo(
                targetValue = targetOffset,
                animationSpec = spring(
                    dampingRatio = Spring.DampingRatioLowBouncy,
                    stiffness = Spring.StiffnessMedium
                )
            )
            if (target == SheetStatus.HIDDEN) {
                status = target
            }
            // Ensure final value sync
            if (target == SheetStatus.EXPANDED && offsetY.value != 0f) offsetY.snapTo(0f)
            if (target == SheetStatus.HIDDEN && offsetY.value != sheetHeightPx) offsetY.snapTo(sheetHeightPx)
        } finally {
            isAnimating = false
        }
    }
    // 실제 바텀시트 높이값을 특정 수치로 이동시킵니다.
    internal fun dispatchSlide() {
        onSlide?.invoke(progress)
    }
    // ==================== 바텀시트 제어 메서드 ====================
    /**
     * 바텀시트를 표시합니다.
     * 데이터 경쟁 조건 방지를 위해 상태 변경과 애니메이션을 순차적으로 처리합니다.
     */
    fun show(
        height: Dp = 280.dp,
        onDismiss: () -> Unit,
        onTapBackNavBtn: () -> Unit,
        isOutTapDismissEnabled: Boolean = true,
        isDragDismissEnabled: Boolean = true,
        content: @Composable () -> Unit
    ) {
        // 애니메이션 진행 중이면 무시
        if (isAnimating) return
        // 속성 설정
        this.height = height
        this.onDismissCallback = onDismiss
        this.onTapBackNavBtnCallback = onTapBackNavBtn
        this.onTapScrimDismissEnabled = isOutTapDismissEnabled
        this.onDragDismissEnabled = isDragDismissEnabled
        this.content = content
        // 애니메이션 시작
        scope.launch {
            animateTo(SheetStatus.EXPANDED)
        }
    }
    /** @hide 자식뷰의 ViewModel 비즈니스 로직을 통해 CustomBottomSheet에 주입되는 isPresent가 false로 변경되면,
     * CustomBottomSheetProvider가 이를 감지하여 hide()를 호출합니다.
     *  */
    fun hide() {
        // 애니메이션 진행 중이면 무시
        if (isAnimating) return
        scope.launch {
            animateTo(SheetStatus.HIDDEN)
        }
    }
    internal fun onSheetDismiss() {
        // 애니메이션 진행 중이면 무시
        if (isAnimating) return

        scope.launch {
            animateTo(SheetStatus.HIDDEN)
            onDismissCallback?.invoke()
        }
    }
    internal fun onTapSheetBackNavBtn() {
        // 애니메이션 진행 중이면 무시
        if (isAnimating) return
        onTapBackNavBtnCallback?.invoke()
    }
    // 드래그 완료 후 상태 결정 및 애니메이션 처리
    internal fun handleDragEnd(velocityY: Float) {
        val currentY = offsetY.value
        val thresholdVelocity = 500f // arbitrary threshold for "Fast"
        val isFlingDown = velocityY > thresholdVelocity
        val isFlingUp = velocityY < -thresholdVelocity
        val target = if (isFlingDown) {
            SheetStatus.HIDDEN
        } else if (isFlingUp) {
            SheetStatus.EXPANDED
        } else {
            if (currentY > sheetHeightPx / 2) SheetStatus.HIDDEN else SheetStatus.EXPANDED // Distance based
        }
        scope.launch {
            animateTo(target)
            if (target == SheetStatus.HIDDEN) {
                onDismissCallback?.invoke()
            }
        }
    }
    // 드래그 취소 시 현재 상태로 복귀
    internal fun handleDragCancel() {
        scope.launch { animateTo(status) }
    }
    // 드래그 중 offset 업데이트
    internal fun handleDrag(dragAmount: Float) {
        scope.launch {
            val resistanceFactor = if (offsetY.value < 0) 0.3f else 1f
            val newOffset = offsetY.value + dragAmount * resistanceFactor
            offsetY.snapTo(newOffset)
        }
    }
}

3.1. 기존 구조의 문제점

초기 구현에서는 CustomBottomSheetState(애니메이션 상태)와 CustomBottomSheetNavigator(바텀시트 속성)를 분리했습니다. 이로 인해 여러 LaunchedEffect가 각각의 상태를 관찰하고 동기화해야 했습니다:

// 기존 구조 - 다수의 LaunchedEffect로 인한 문제
@Composable
fun BottomSheet(...) {  // LaunchedEffect 1: isPresent 변화 감지
  LaunchedEffect(isPresent) {
  if (isPresent) navigator.show(...) else navigator.hide()
  }
  // LaunchedEffect 2: sheetState 연결
  LaunchedEffect(sheetState) {
      navigator.sheetState = sheetState
  }
  // LaunchedEffect 3: 높이 업데이트
  LaunchedEffect(sheetHeightPx) {
      state.updateSheetHeight(sheetHeightPx)
  }
  // LaunchedEffect 4: 상태 변화 콜백
  LaunchedEffect(state.status) {
      if (state.status == SheetStatus.HIDDEN && isPresent) {
          onDismiss?.invoke()
      }
  }
  ...
}

3.2. Compose 프레임 사이클과 데이터 경쟁 조건

Compose는 다음과 같은 3단계 프레임 사이클을 거칩니다.

핵심 문제: LaunchedEffect들은 Composition이 완료된 후 같은 시점에 동시에 스케줄됩니다. 실행 순서는 코루틴 디스패처에 의존하며 보장되지 않습니다. 이로 인해 다음과 같은 데이터 경쟁 조건이 발생했습니다.

경쟁 조건 시나리오

LaunchedEffect A: isPresent=true 감지 → show() 호출

LaunchedEffect B: sheetHeightPx 변경 감지 → offset 조정

LaunchedEffect C: status 변경 감지 → 콜백 호출

실행 순서가 보장되지 않아 다음과 같은 문제 발생:

1. show()가 아직 완료되지 않은 상태에서 offset이 조정됨

2. 애니메이션 중간에 상태가 변경되어 화면 깜빡임 발생

3. 콜백이 예상치 못한 시점에 호출됨

3.3. 해결책: 단일 Controller로 통합

BottomSheetState와 CustomBottomSheetNavigator를 CustomBottomSheetController 하나로 통합했습니다.

@Stable
class CustomBottomSheetController(val scope: CoroutineScope) {
  // ==================== 애니메이션 상태 (기존 BottomSheetState) ====================
  var status by mutableStateOf(SheetStatus.HIDDEN)
      private set
  // 애니메이션 진행 중 플래그 - 경쟁 조건 방지의 핵심
  var isAnimating by mutableStateOf(false)
      private set
  val offsetY = Animatable(0f)
  var sheetHeightPx by mutableFloatStateOf(0f)
      private set
  // ==================== 바텀시트 속성 (기존 Navigator) ====================
  var content by mutableStateOf<@Composable () -> Unit>({})
      private set
  var height by mutableStateOf(280.dp)
      private set
  private var onDismissCallback: (() -> Unit)? = null
  // ...
}

@Stable 어노테이션은 Compose 컴파일러에게 이 클래스의 인스턴스가 안정적임을 알립니다. 모든 가변 프로퍼티가 MutableState로 래핑되어 있으므로 변경 시 Composition에 자동으로 알림이 전달됩니다. 이로써 Controller를 파라미터로 받는 Composable에서 불필요한 Recomposition이 방지됩니다.

3.4. isAnimating 플래그를 통한 경쟁 조건 방지

2 인스턴스를 단일 객체로 통합한 후에는 애니메이션이 진행 중일 때 추가적인 상태 변경을 차단하는 isAnimating 플래그를 도입하여 레이스 컨디션을 해결했습니다.

internal suspend fun animateTo(target: SheetStatus) {
// 애니메이션 진행 중이면 무시 - 중복 호출 방지
if (isAnimating) return
  isAnimating = true
  try {
      // EXPANDED로 전환 시: 먼저 status 변경 후 애니메이션
      // → UI가 즉시 표시되고 애니메이션이 부드럽게 진행
      if (target == SheetStatus.EXPANDED) {
          status = target
      }
      offsetY.animateTo(
          targetValue = targetOffset,
          animationSpec = spring(
              dampingRatio = Spring.DampingRatioLowBouncy,
              stiffness = Spring.StiffnessMedium
          )
      )
      // HIDDEN으로 전환 시: 애니메이션 완료 후 status 변경
      // → 애니메이션이 끝까지 재생된 후 UI 제거
      if (target == SheetStatus.HIDDEN) {
          status = target
      }
  } finally {
      isAnimating = false
  }
  ```
}

3.5. 높이 업데이트 시 애니메이션 보호

updateSheetHeight 메서드에서도 애니메이션 상태를 확인합니다.

internal fun updateSheetHeight(heightPx: Float) {
  if (this.sheetHeightPx != heightPx) {
    this.sheetHeightPx = heightPx
    // 애니메이션 중이면 높이만 업데이트하고 offset 조정은 스킵
    // → snapTo()가 animateTo()를 취소시키는 문제 방지
    if (isAnimating) return
    if (status == SheetStatus.HIDDEN) {
        scope.launch { offsetY.snapTo(heightPx) }
    } else if (status == SheetStatus.EXPANDED) {
        scope.launch { offsetY.snapTo(0f) }
    }
  }
  ```
}

Animatable.snapTo()는 진행 중인 animateTo()를 즉시 취소시킵니다. 애니메이션 중에 snapTo()가 호출되면 애니메이션이 중단되고 값이 점프하여 사용자 경험이 저하됩니다. isAnimating 플래그로 이를 방지합니다.

4. InternalCustomBottomSheet: UI 컴포넌트

// 전체 코드
@Composable
fun InternalCustomBottomSheet(
    controller: CustomBottomSheetController,
    content: @Composable () -> Unit
) {
    val density = LocalDensity.current
    val navBottomPadding = WindowInsets.navigationBars.asPaddingValues().calculateBottomPadding()
    // 하단 네비게이션 바 높이를 포함한 전체 높이값입니다.
    val fullSheetHeight = controller.height + navBottomPadding
    val sheetHeightPx = with(density) { fullSheetHeight.toPx() }
    // CustomBottomSheet가 포함된 자식뷰가 구성될 때, 자식뷰에서 정의한 height는 controller에 의해 이곳으로 주입되며 이에 맞춰 Px로 변환됩니다.
    // Composition 시점에 동기적으로 높이 업데이트 (LaunchedEffect 제거로 경쟁 조건 방지)
    controller.updateSheetHeight(sheetHeightPx)
    // offsetY 변경 시 슬라이드 콜백 호출
    controller.dispatchSlide()
    if (controller.status != SheetStatus.HIDDEN) {
        BackHandler(enabled = controller.status != SheetStatus.HIDDEN) {
            controller.onTapSheetBackNavBtn()
        }
        Box(
            modifier = Modifier.fillMaxSize(),
            contentAlignment = Alignment.BottomCenter
        ) {
            if (controller.status != SheetStatus.HIDDEN || controller.offsetY.value < controller.sheetHeightPx) {
                Box(
                    modifier = Modifier
                        .fillMaxSize()
                        .graphicsLayer {
                            alpha = (controller.progress * 0.4f).coerceIn(0f, 0.4f)
                        }
                        .background(Color.Black)
                        .pointerInput(Unit) {
                            detectTapGestures(
                                onTap = {
                                    if (controller.onTapScrimDismissEnabled) {
                                        controller.onSheetDismiss()
                                    }
                                }
                            )
                        }
                )
            }
            // Sheet Content
            Column(
                modifier = Modifier
                    .widthIn(max = 420.dp)
                    .offset { IntOffset(0, controller.offsetY.value.roundToInt()) }
                    .height(fullSheetHeight)
                    .padding(bottom = navBottomPadding)
                    .background(
                        color = Gray10,
                        shape = RoundedCornerShape(topStart = 24.dp, topEnd = 24.dp)
                    )
                    .drawBehind {
                        drawRect(
                            color = Gray10,
                            topLeft = Offset(0f, size.height - 1f), // Overlap 1px to avoid gap
                            size = Size(size.width, density.density * 1000f) // Extend 1000dp down
                        )
                    }
                    // Apply Drag Gesture to the whole sheet container
                    .pointerInput(controller.onDragDismissEnabled) {
                        if (!controller.onDragDismissEnabled) return@pointerInput
                        val velocityTracker = VelocityTracker()
                        detectVerticalDragGestures(
                            onDragStart = {
                                velocityTracker.resetTracking()
                            },
                            onDragEnd = {
                                // Req 2.2: Decision
                                val velocityY = velocityTracker.calculateVelocity().y
                                controller.handleDragEnd(velocityY)
                            },
                            onDragCancel = {
                                controller.handleDragCancel()
                            }
                        ) { change, dragAmount ->
                            change.consume()
                            controller.handleDrag(dragAmount)
                        }
                    }
            ) {
                content()
            }
        }
    }
}

4.1. 저항 계수(Resistance Factor) 구현

Jetpack Compose의 ModalBottomSheet와 iOS SwiftUI의 기본 바텀시트의 경우, 한계점 위로 더 드래그 동작을 수행할 경우, 고무줄처럼 팽팽하게 늘어나는 효과를 줍니다. 이와 동일한 시각적 효과를 부여하기 위해 드래그 업데이트 로직에 저항 계수를 도입했습니다.

internal fun handleDrag(dragAmount: Float) {
  scope.launch {
    // offsetY < 0: 바텀시트가 최대 높이 위로 올라간 상태
    val resistanceFactor = if (offsetY.value < 0) 0.3f else 1f
    val newOffset = offsetY.value + dragAmount * resistanceFactor
    offsetY.snapTo(newOffset)
  }
}

offsetY가 0보다 작아지는 순간(이미 완전히 펼쳐진 상태에서 위로 더 당기는 경우), 드래그 거리의 30%만 반영됩니다. 이는 iOS의 rubber banding 효과와 동일한 사용자 경험을 제공합니다.

4.2. 속도(Fling)와 거리(Distance) 적용

사용자가 바텀시트를 놓았을 때, 바텀시트를 닫을지 다시 펼칠지를 결정하는 로직을 구현하기 위해 저는 두 가지 기준을 결합하여 판정 로직을 구축했습니다.

• 관성(Fling) 기반: 사용자가 아래로 빠르게 튕기면, 현재 위치와 상관없이 ‘닫으려는 의도’로 간주하고 즉시 HIDDEN으로 보냅니다.
• 거리(Distance) 기반: 천천히 움직일 때는 바텀시트 전체 높이의 50%를 기준점으로 삼습니다. 절반 이하로 내렸다면 다시 돌아오고, 절반 이상 내렸다면 닫힙니다.

internal fun handleDragEnd(velocityY: Float) {
    val currentY = offsetY.value
    val thresholdVelocity = 500f
    val isFlingDown = velocityY > thresholdVelocity
    val isFlingUp = velocityY < -thresholdVelocity
  
    val target = when {
        isFlingDown -> SheetStatus.HIDDEN      // 빠르게 아래로 튕김
        isFlingUp -> SheetStatus.EXPANDED      // 빠르게 위로 튕김
        currentY > sheetHeightPx / 2 -> SheetStatus.HIDDEN   // 50% 이상 내림
        else -> SheetStatus.EXPANDED                          // 50% 미만 내림
    }
  
    scope.launch {
        animateTo(target)
        if (target == SheetStatus.HIDDEN) {
            onDismissCallback?.invoke()
        }
    }
  
  ```
}

4.3. Scrim 애니메이션과 graphicsLayer 최적화

Box(
  modifier = Modifier
    .fillMaxSize()
    .graphicsLayer {
        alpha = (controller.progress * 0.4f).coerceIn(0f, 0.4f)
    }
    .background(Color.Black)
)

graphicsLayer의 람다 버전을 사용한 이유:

1. 그리기 단계 격리: 람다 버전은 Drawing 단계에서만 실행되어, alpha 값 변경이 Recomposition을 트리거하지 않습니다.
2. 하드웨어 가속: graphicsLayer는 별도의 렌더링 레이어를 생성하여 GPU 가속을 활용합니다.
3. 성능 최적화: 60fps 애니메이션에서 매 프레임 Recomposition 없이 투명도만 변경됩니다.

이를 통해 시트가 위로 올라올수록 배경은 자연스럽게 어두워집니다.

4.4. drawBehind를 통한 하단 영역 확장

현재 바텀시트가 펼쳐진 상태에서 상단으로 드래그를 할 경우, 저항계수가 적용된 채로 바텀시트가 더 올라가도록 설계가 되어있지만, 바텀시트 UI 영역 자체의 높이값은 초기 SheetState에서 계산된 height만 감싸기 때문에, 바텀시트가 끊어져 보이는 현상이 발생합니다.

이를 해결하기 위해 drawBehind 수정자를 활용하여 하단에 하얀 배경의 여백을 추가했습니다.

.drawBehind {
    drawRect(
        color = Gray10,
        topLeft = Offset(0f, size.height - 1f),
        size = Size(size.width, density.density * 1000f) // 하단으로 1000dp만큼 연장
    )
}

drawBehind는 Drawing 단계에서 실행되므로 Composition이나 Layout에 영향을 주지 않습니다. 1000dp 높이의 사각형을 그려어떤 오버스크롤 상황에서도 배경색이 유지됩니다.

5. CustomBottomSheetProvider: 전역 주입

만일 InternalBottomSheet를 바텀시트를 표시해야하는 Screen에서 바로 호출하게 될 경우, 앱 내부의 바텀 네비게이션 탭에 의해 바텀시트 일부가 가려지는 이슈가 존재 했습니다.

때문에, 바텀 네비게이션 탭보다 위에 표시되게 하기 위해, BottomSheet가 표시되는 위치를 Root로 이동시켜야 합니다.

val LocalCustomBottomSheetController = compositionLocalOf<CustomBottomSheetController> {
    error("No CustomBottomSheetController provided")
}

@Composable
fun CustomBottomSheetProvider(content: @Composable () -> Unit) {
  val scope = rememberCoroutineScope()
  val controller = remember(scope) { CustomBottomSheetController(scope) }
  
    CompositionLocalProvider(LocalCustomBottomSheetController provides controller) {
        Box(modifier = Modifier.fillMaxSize()) {
            content()  // 앱의 실제 화면들
  
            // Z-index 최상위에 바텀시트 배치
            InternalCustomBottomSheet(controller = controller) {
                controller.content()
            }
        }
    }
}

// 앱 루트
@AndroidEntryPoint
class MainActivity : ComponentActivity() {
    override fun onStart() {
        super.onStart()
        ...
    }
    override fun onCreate(savedInstanceState: Bundle?) {
        ...
        setContent {
            CustomBottomSheetProvider { // 바텀시트 호출 위치
                // 앱 화면
            }
        }
    }
    override fun onDestroy() {
        super.onDestroy()
    }
}

이때, CompositionLocalProvider를 통해 controller를 하위 모든 Composable에 암시적으로 전달합니다. 이는 iOS의 @EnvironmentObject와 유사한 역할을 수행합니다.

6. CustomBottomSheet: 선언형 API

최종 사용 API는 iOS SwiftUI의 .sheet(isPresented:)와 유사합니다:

@Composable
fun CustomBottomSheet(
  isPresent: Boolean,
  height: Dp = 280.dp,
  onDismiss: () -> Unit,
  onTapBackNavBtn: (() -> Unit)? = null,
  onTapScrimDismissEnabled: Boolean = true,
  onDragDismissEnabled: Boolean = true,
  content: @Composable () -> Unit
) {
  val controller = LocalCustomBottomSheetController.current
  val currentOnDismiss by rememberUpdatedState(onDismiss)
  val currentContent by rememberUpdatedState(content)

  LaunchedEffect(isPresent, height) {
      if (isPresent) {
          controller.show(
              height = height,
              onDismiss = { currentOnDismiss() },
              onTapBackNavBtn = currentOnTapBackNavBtn ?: onDismiss,
              isOutTapDismissEnabled = onTapScrimDismissEnabled,
              isDragDismissEnabled = onDragDismissEnabled,
              content = { currentContent() }
          )
      } else {
          controller.hide()
      }
  }

  DisposableEffect(Unit) {
      onDispose {
          if (isPresent) {
              controller.hide()
              currentOnDismiss()
          }
      }
  }
}

6.1. rememberUpdatedState의 역할

LaunchedEffect는 키 값이 변경될 때만 재시작됩니다. 하지만 onDismiss 콜백 자체는 Recomposition마다 새로운 람다 인스턴스가 될 수 있습니다. rememberUpdatedState는 항상 최신 콜백 참조를 유지하면서 LaunchedEffect 재시작을 방지합니다.

6.2. DisposableEffect를 통한 정리

화면 이동 등으로 Composable이 Composition에서 제거될 때, 열려있는 바텀시트를 정리합니다.

DisposableEffect(Unit) {
  onDispose {
    if (isPresent) {
      controller.hide()
      currentOnDismiss()
    }
}

6.3.실제 사용 예시

@Composable
fun MyScreen(viewModel: MyViewModel) {
val uiState by viewModel.uiState.collectAsState()
```
  CustomBottomSheet(
      isPresent = uiState.isBottomSheetVisible,
      height = 320.dp,
      onDismiss = { // 바텀시트가 내려갈때, 수행되어야 할 로직}
  ) {
      // 바텀시트 내용
  }
  // 나머지 화면 구성...
```
}

7. 결론

이번 커스텀 바텀시트 구현을 통해 아래 핵심 인사이트들을 얻을 수 있었습니다.

7.1. 데이터 경쟁 조건 해결

• 문제: 다수의 LaunchedEffect가 동시에 스케줄되어 실행 순서가 보장되지 않음
• 해결: 상태와 애니메이션을 단일 Controller로 통합하고, isAnimating 플래그로 중복 호출 차단
• 교훈: Compose에서 복잡한 상태 동기화가 필요할 때, 여러 LaunchedEffect보다 단일 상태 홀더가 더 안전하다는 것을 체감했습니다.

7.2. Compose 프레임 사이클 이해

• Composition → Layout → Drawing 순서 이해가 필수
• LaunchedEffect는 Drawing 이후 실행되므로 동기적 초기화가 필요한 경우 주의가 필요하다는 것을 알게 되었습니다.
• graphicsLayer 람다 버전은 Drawing 단계에서만 실행되어 성능 최적화에 유리합니다.

때로는 라이브러리를 가져다 쓰는 것이 가장 빠르고 효율적인 정답일 수 있습니다. 하지만 서비스의 핵심 경험이 되는 컴포넌트라면, 원리를 파헤치고 직접 구현해 보는 과정이 필수적이라고 생각합니다.

긴 글 읽어주셔서 감사합니다. 궁금하신 점이나 더 나은 구현 방식에 대한 의견은 댓글로 언제든 환영입니다 :)

8. 문제해결과정- 바텀시트 표시 간, 시스템 Back 이벤트 미도달 이슈

iOS에서의 바텀시트 표시로직을 제어할때와 달리, android는 소프트웨어 네비게이션 버튼을 통해 바텀시트가 표시되어있을 동안, 뒤로가기 이벤트 호출이 가능합니다. 만일 바텀시트 내부에 2개 이상의 뎁스가 존재할 경우, 뒤로가기 이벤트가 바텀시트 hide 뿐만 아니라 자식뷰에서 전달하는 비즈니스 로직 콜백도 호출할 수 있어야 했기에, CustomBottomSheet api를 통해 onTapBackNavBtn 인자를 전달한 후, InternalBottomSheet 컴포저블에서 BackHandler 훅을 사용하여 Back 이벤트 핸들링을 처리하고자 했습니다.

@Composable
fun InternalHMBottomSheet(
    controller: HMBottomSheetController,
    content: @Composable () -> Unit
) {
    ...
    // Controller에서 관리 및 저장하는 SystemBack 이벤트 콜백을 BackHandler 내부에서 호출
    BackHandler(enabled = controller.status != HMSheetStatus.HIDDEN) {
      controller.onTapSheetBackNavBtn()
    }

    if (controller.status != HMSheetStatus.HIDDEN) {
      // 바텀시트
    }
}

하지만, 바텀시트가 표시된 상태에서 System Back을 호출하여도 바텀시트는 그대로 유지되고, 이를 호출한 자식뷰에서의 뒤로가기 동작이 대신 수행되는 문제가 있었습니다.

이를 해결하기 위해, BackHandler의 공식문서와 내부 구현 코드를 봤습니다.

이를 확인하고자, BottomSheet 내부 BackHandler가 호출되게끔 BottomSheet api를 호출한 자식뷰를 구성하기까지의 tree 구조 상에서 Backhandler를 모두 제거하였으나, backStack에 화면이 남아있을때는 pop() 동작이 호출되나, 더이상 뒤로갈 화면이 없을 때에만 바텀시트가 내려가는 상황이 재현되었습니다.

이러한 현상의 원인은 NavHost의 내부 구조때문이였습니다.

@Composable
public fun NavHost(
    ...
) {
    ...
    val currentBackStack by composeNavigator.backStack.collectAsState()
    // backStack이 남아있을 때에 BackHandler 내부 콜백이 호출됨!
    BackHandler(currentBackStack.size > 1) {
        navController.popBackStack()
    }
}

CustomBottomSheetProvider {  
      Box {
          NavHost {
              ...
          }
          // 동일한 위계 상에 위치한 BottomSheet 내부 Backhandler는 
          // NavHost의 BackHandler가 호출되지 않을때 호출됨.
          InternalCustomBottomSheet(...)  
      }
  }

여기서 2차로 의문점이 든 것은 NavHost보다 BottomSheet 컴포저블 함수가 더 밑에 선언되어있기에 Top-down 방향으로 호출되는 Jetpack Compose의 구성 사이클에 따라 BottomSheet의 BackHandler가 무조건 우선순위를 점하는게 정상이지 않을까? 였습니다.

CustomBottomSheetProvider {
    Box {
        NavHost {
            ... // 1. 여기서 내장된 Backhandler 등록하고 내부 컴포저블 함수 실행
        }
        
        InternalCustomBottomSheet(...)  // 2. 내부 Backhandler 등록
    }
}

하지만, 이는 BackHandler의 내부구현 코드를 통해 해소될 수 있었습니다.

@Composable
public fun BackHandler(enabled: Boolean = true, onBack: () -> Unit) {
    // Back 콜백을 계속 추적하며 가장 최근에 주입된 값으로 바꿔끼고 있음
    val currentOnBack by rememberUpdatedState(onBack)
    val backCallback = remember {
        object : OnBackPressedCallback(enabled) {
            override fun handleOnBackPressed() {
                currentOnBack()
            }
        }
    }
    ...
}

BackHandler가 가장 nested Screen에서 등록된 것이 최종 실행된다고 공식문서에서 이유는, BackHandler는 내부적으로 가장 최종으로 등록된 onBack만을 저장하고 호출하기 때문입니다.

NavHost는 내부에 선언된 Screen들의 상태변수에 따라 재구성될 수 있으며, 이때마다 BackHandler를 재등록할 수 있습니다. 때문에, 같은 위계 상 더 상단에 위치하였음에도 BackHandler 콜백을 가로챌 수 있던 것입니다.

특히, 선언형 구조로 바텀시트를 제어하기 위해 바텀시트 표시 간 isPresent의 불린 타입 상태변수를 ViewModel에서 관리 및 제어하고 있었기에, 바텀시트를 열 경우, isPresent를 관리하는 자식 뷰의 상태가 변경됨에 따라 재구성되었고, 이를 포함하고 있던 NavHost 또한 재구성이 되며 BackHandler가 재등록되고 있었습니다.

@Composable
fun InternalHMBottomSheet(
    controller: HMBottomSheetController,
    content: @Composable () -> Unit
) {
    ...
    // NavHost의 BackHandler 재등록 타이밍보다 이르게 도달됨

    if (controller.status != HMSheetStatus.HIDDEN) {
      // 바텀시트 표시 애니메이션 완료 후, State가 변경됨에 따라 가장 최종적으로 도달됨
      // BackHandler를 안정적으로 등록할 수 있음
      BackHandler(enabled = controller.status != HMSheetStatus.HIDDEN) {
        controller.onTapSheetBackNavBtn()
      }
      // 바텀시트
    }
}

때문에, BackHandler를 조건부 composition 블록 내부에 배치함으로써 등록 시점을 의도적으로 늦추어 바텀시트에 대한 Back 이벤트를 안정적으로 호출할 수 있도록 하여 해결할 수 있었습니다.

감사합니다.

Wheel Picker를 직접 구현하는 결정을 내린 이유는, 우선
1. Jetpack Compose는 SwiftUI와 달리 Wheel Picker를 기본제공하지 않았습니다.
2. 이를 위해 가장 많이 사용되는 서드파티 라이브러리의 경우(하단 참조), SwiftUI에서의 기본 api와 달리 인접 아이템을 탭했을 때, 포커스가 바로 이동하지 않아 사용자 경험이 떨어졌습니다.
3. 그 외에도, 포커스 하이라이트, 페이드 등 UX를 결정짓는 UI 요소들이 큰 차이를 보였습니다.

GitHub - zj565061763/compose-wheel-picker: Android Compose wheel picker library based on LazyColumn in vertical and LazyRow in horizontal.

무엇보다 앱 핵심 기능 수행을 위한 상호작용 시에는 안드로이드와 iOS 간 룩앤필은 큰 차이가 없어야 한다는 개인 원칙 때문에 공수를 더 들여서라도 커스텀 작업을 진행하게 되었습니다.

1. Wheel Picker 초기 구현

초기 피커 UI 구현에 가장 많이 참고한 레퍼런스는 Stack Overflow에서 제시된 InfiniteCircularList 였습니다.

Is there a way to create Scroll Wheel in Jetpack Compose?

해당 모듈에서는 나머지 연산자를 중심으로 LazyColumn에서 다루는 item element가 단방향으로 스와이프하여도 계속 순환하여 보이게끔 설계되어있었습니다. 유한한 범위 내에서의 선택이 목적이였던 만큼 해당 코드를 무한순환 로직을 아래와 같이 제거하였습니다.

@Composable
fun MyPicker(
    itemHeight: Dp,
    numberOfDisplayedItems: Int = 3,
    unit: String,
    items: List<String>,
    initialItem: String,
    textStyle: TextStyle,
    textColor: Color,
    onItemSelected: (index: Int, item: String) -> Unit = { _, _ -> }
) {
    val itemHalfHeight = LocalDensity.current.run { itemHeight.toPx() / 2f }
    val scrollState = rememberLazyListState(0)
    var lastSelectedIndex by remember {
        mutableStateOf(0)
    }

    var itemsState by remember {
        mutableStateOf(items)
    }

    LaunchedEffect(Unit) {
        val initialItemIndex = items.indexOf(initialItem)

        itemsState = List(1) { "" } + items + List(1) { "" }
        lastSelectedIndex = initialItemIndex
        scrollState.scrollToItem(initialItemIndex)
    }

    Box(
        modifier = Modifier.fillMaxSize(),
        contentAlignment = Alignment.Center
    ) {
        LazyColumn(
            modifier = Modifier
                .fillMaxWidth()
                .height(itemHeight * numberOfDisplayedItems),
            state = scrollState,
            flingBehavior = rememberSnapFlingBehavior(
                lazyListState = scrollState
            )
        ) {
            items(
                count = itemsState.size,
                itemContent = { i ->
                    val item = itemsState[i]
                    val isSelected = lastSelectedIndex == i

                    Row(
                        modifier = Modifier
                            .height(itemHeight)
                            .fillMaxWidth()
                            .onGloballyPositioned { coordinates ->
                                val y = coordinates.positionInParent().y + itemHalfHeight
                                val parentHalfHeight = (itemHalfHeight * numberOfDisplayedItems)
                                val isCurrentlySelected = (parentHalfHeight - itemHalfHeight < y && y < parentHalfHeight + itemHalfHeight)
                                if (isCurrentlySelected && lastSelectedIndex != i && item.isNotEmpty()) {
                                    onItemSelected(i - 1, item) // i-1 because first item is empty padding
                                    lastSelectedIndex = i
                                }
                            },
                        horizontalArrangement = Arrangement.Center
                    ) {
                        if (item.toString().isNotEmpty()) {
                            Text(
                                text = item.toString(),
                                style = textStyle,
                                modifier = Modifier.padding(end = 4.dp),
                                color = if (isSelected) Gray80 else textColor.copy(alpha = 0.6f),
                                fontSize = if (isSelected) textStyle.fontSize * 1.2f else textStyle.fontSize
                            )

                            Text(
                                text = unit,
                                style = textStyle,
                                color = if (isSelected) Gray80 else textColor.copy(alpha = 0.6f),
                                fontSize = if (isSelected) textStyle.fontSize * 1.2f else textStyle.fontSize
                            )
                        }
                    }
                }
            )
        }

        Box(
            modifier = Modifier
                .fillMaxWidth()
                .height(itemHeight)
                .drawWithContent {
                    drawContent()
                    drawRoundRect(
                        color = Gray20,
                        cornerRadius = CornerRadius(8.dp.toPx(), 8.dp.toPx()),
                        blendMode = BlendMode.Multiply
                    )
                }
        )
    }
}

1. itemHeight, numberOfDisplayedItems, unit 등을 외부에서 주입받아 재사용할 수 있도록 설계
2. LaunchedEffect(Unit)에서 주입받은 초기 아이템이 위치한 offset으로 스크롤되도록 고도화

3. onGloballyPositioned로 항목 중심 좌표를 비교하며 포커스 판별

onGloballyPositioned가 호출되는 시점
1. 초기 레이아웃 배치되는 경우
2. 사용자에 의한 스크롤이나 scrollToItem으로 위치나 크기가 변경되는 경우
3. 재평가 후 실제 레이아웃이 변경되는 경우

하지만 무한 순환 로직을 제거하게 되면서, 피커 UI의 중앙에 첫번째 아이템과 마지막 아이템을 선택하지 못하는 치명적인 이슈가 있었습니다.

Wheel Picker UI 특성상, 드래그 동작을 통해 선택하고자 하는 item을 중앙으로 이동시켜야 포커싱이 가능한데, 아이템을 중앙으로 옮겨줄 수 있는 인접 Padding이 부재했기 때문입니다.

해당 문제를 해결하고자, List(1) { “” } + items + List(1) { “” } 와 같이, 더미 항목을 아이템 배열 앞뒤에 붙임으로써 해결하였습니다.

하지만 numberOfDisplayedItems와 itemHeight에 맞춰 LazyColumn의 높이 강제가 필요했고, numberOfDisplayedItems에 짝수를 전달할 시 아래와 같이 정중앙이 비어 포커스가 틀어지는 문제가 있었습니다.

차지하는 영역에 따라 UI가 동적으로 배치되는 것이 아닌, 주어진 인자에 따라 정적인 UI를 구성하는 설계 방향은 폴더블과 같은 다양한 폼팩터에 대응해야하는 안드로이드에는 치명적인 제약으로 다가왔습니다.

때문에 SwiftUI의 Picker처럼 “영역에 맞춰 자동으로 높이를 계산하는 구조”로의 변경이 불가피했습니다.

2. SubcomposeLayout을 통한 높이 계산 로직 추가

지정된 영역 내에서의 아이템 정렬을 구현하기 위해, Jetpack Compose가 제공하는 SubcomposeLayout을 사용하였습니다. SubcomposeLayout은 커스텀 레이아웃 도구로, 측정(measure) 단계에서 필요한 슬롯만 별도 서브 컴포지션 (subcomposition) 해 높이·너비를 직접 얻을 수 있습니다.

@Composable
fun TestPicker(
    modifier: Modifier = Modifier,
    items: List<String>,
    initialItem: String,
    onItemSelected: (Int, String) -> Unit = { _, _ -> },
    content: @Composable ((String, Boolean) -> Unit)
) {
    val density = LocalDensity.current
    val scrollState = rememberLazyListState(0)
    var lastSelectedIndex by remember { mutableStateOf(0) }
    var itemsState by remember { mutableStateOf(items) }
    var itemHeight by remember { mutableStateOf(0.dp) }
    var itemHeightPx by remember { mutableStateOf(0f) }
    var pickerHeight by remember { mutableStateOf(0.dp) }
    var pickerHeightPx by remember { mutableStateOf(0f) }

    SubcomposeLayout { constraints ->
        println("SubcomposeLayout 실행:${System.currentTimeMillis()}")
        if (itemHeight == 0.dp) {
            val sampleItem = items.firstOrNull() ?: ""
            val measurables = subcompose("sample") {
                content(sampleItem, false)
            }
            val placeables = measurables.map { it.measure(constraints) }
            val heightPx = placeables.firstOrNull()?.height?.toFloat() ?: 0f
            itemHeight = with(density) { heightPx.toDp() }
            itemHeightPx = heightPx
        }

        layout(0, 0) {}
    }

    LaunchedEffect(itemHeightPx, pickerHeightPx) {
        println("LaunchedEffect 실행:${System.currentTimeMillis()}")
        if (itemHeightPx > 0f && pickerHeightPx > 0f) {
            val paddingItemsCount = kotlin.math.floor((pickerHeightPx / 2f) / itemHeightPx).toInt()
            itemsState = List(paddingItemsCount) { "" } + items + List(paddingItemsCount) { "" }
            val targetIndex = items.indexOf(initialItem)
            lastSelectedIndex = targetIndex
            scrollState.scrollToItem(targetIndex)
        }
    }

    Box(
        modifier = modifier
            .fillMaxWidth()
            .onGloballyPositioned { coordinates ->
                val actualHeightPx = coordinates.size.height.toFloat()
                if (actualHeightPx > 0f && pickerHeightPx != actualHeightPx) {
                    pickerHeightPx = actualHeightPx
                    pickerHeight = with(density) { actualHeightPx.toDp() }
                }
            },
        contentAlignment = Alignment.Center
    ) {
        LazyColumn(
            modifier = Modifier.fillMaxSize(),
            state = scrollState,
            flingBehavior = rememberSnapFlingBehavior(
                lazyListState = scrollState
            )
        ) {
            items(
                count = itemsState.size,
                itemContent = { i ->
                    val item = itemsState[i]
                    val isSelected = lastSelectedIndex == i

                    Row(
                        modifier = Modifier
                            .fillMaxWidth()
                            .height(itemHeight)
                            .onGloballyPositioned { coordinates ->
                                if (pickerHeightPx > 0f && itemHeightPx > 0f) {
                                    val y = (coordinates.positionInParent().y) + (itemHeightPx / 2f)
                                    val parentHalfHeight = (pickerHeightPx / 2f)
                                    val isCurrentlySelected = abs(parentHalfHeight - y) <= (itemHeightPx / 2f)

                                    if (isCurrentlySelected && lastSelectedIndex != i && item.isNotEmpty()) {
                                        val paddingItemsCount = floor((pickerHeightPx / 2f) / itemHeightPx).toInt()
                                        val actualIndex = i - paddingItemsCount
                                        if (actualIndex >= 0 && actualIndex < items.size) {
                                            onItemSelected(actualIndex, item)
                                            lastSelectedIndex = i
                                        }
                                    }
                                }
                            },
                        horizontalArrangement = Arrangement.Center
                    ) {
                        content(item.toString(), isSelected)
                    }
                }
            )
        }

        Box(
            modifier = Modifier
                .fillMaxWidth()
                .height(itemHeight)
                .drawWithContent {
                    drawRoundRect(
                        color = Gray20,
                        cornerRadius = CornerRadius(8.dp.toPx()),
                        blendMode = BlendMode.Multiply
                    )
                }
        )
    }
}

Compose는 매 프레임마다 (1) 재구성(recomposition) → (2) 레이아웃(측정→배치) → (3) 드로잉 순으로 진행하는데, SubcomposeLayout 블록은 2단계의 “측정” 시점에 호출됩니다. 따라서 최종 구현된 패턴은 아래 순서와 같았습니다.

1. SubcomposeLayout { constraints -> … } 내부에서 content(sampleItem, false)를 subcompose하여, 아이템 높이(itemHeightPx) 측정
2. 같은 측정 단계에서 부모가 확보한 영역을 onGloballyPositioned로 기록해 pickerHeightPx에 저장
3. 레이아웃 단계 이후, 첫 번째 LaunchedEffect(itemHeightPx, pickerHeightPx)가 실행되면서 상태 변경
4. 동일 LaunchedEffect안에서 paddingItemsCount를 계산하고, 더미 항목을 양끝에 붙인 itemsState를 만든 뒤 scrollState.scrollToItem(targetIndex)로 초기 스크롤

하지만, 부모 컴포저블로부터 제공받은 영역을 100% 활용함에도 불구하고, 양 끝 Padding은 item 단위로 추가되다 보니, 스냅되는 item offset이 중앙을 살짝 이탈하는 이슈가 있었습니다.

SubcomposeLayout의 제약(재진입성)

또한, measurement 단계에서 Composition을 수행하는 SubcomposeLayout의 재진입 동작은 상태 읽기/쓰기 타이밍을 복잡하게 만들고, 예기치 않은 재컴포지션을 유발할 수 있었습니다.

특히, LaunchedEffect는 해당 컴포저블이 Composition 단계에 들어올때 coroutine을 시작하고 나가면 취소되는데, SubcomposeLayout은 측정 중에 subcompose를 여러 번 호출하거나 슬롯을 새로 만들 수 있어 해당 컴포저블이 여러 번 enter/leave 하거나 여러 인스턴스가 생성될 가능성이 크며, 이로 인해 LaunchedEffect가 여러 번 실행될 수 있었습니다.

SubcomposeLayout 실행:1759940310247
SubcomposeLayout 실행:1759940310349
LaunchedEffect 실행:1759940310434
// 초기 Compose 단계에서 불필요한 재호출 발생
Skipped 40 frames!  The application may be doing too much work on its main thread.
SubcomposeLayout 실행:1759940310877
LaunchedEffect 실행:1759940310905

실제로, SubcomposeLayout과 LaunchedEffect에 로그를 심어둔 결과, 위와 같이 불필요한 재호출이 일어나고 있음을 확인할 수 있었습니다.

이는 당장 해결이 필요한 문제는 아니였지만, 추후 재컴포지션으로 의도치 않은 동작을 야기할 수 있었기에 변수를 아예 제거하는 방향으로 고도화 결정을 내리게 되었습니다.

3. 렌더링 로직 재설계

상기 문제들을 해결하기 위해 우선
1. SubcomposeLayout를 활용하였던 초기 측정로직 복잡도를 개선하였으며,
2. 패딩 아이템 대신 영역 높이 기반 정확한 수치를 사이에 삽입하였습니다.

@Composable
fun Picker(
    modifier: Modifier = Modifier,
    items: List<String>,
    initialItem: String,
    onItemSelected: (Int, String) -> Unit = { _, _ -> },
    content: @Composable ((String, Boolean) -> Unit)
) {
    val density = LocalDensity.current
    val scrollState = rememberLazyListState(0)
    var lastSelectedIndex by remember { mutableStateOf(0) }

    val itemHeight = 44.dp
    val itemHeightPx = with(density) { itemHeight.toPx() }

    BoxWithConstraints(
        modifier = modifier.fillMaxWidth(),
        contentAlignment = Alignment.Center
    ) {
        val availableHeight = this.constraints.maxHeight.toFloat()
        /** 부모 뷰로부터 할당받은 영역을 최대한 활용토록 하되, 220.dp를 상한선으로 설정합니다. */
        val currentPickerHeightPx = if (availableHeight == Constraints.Infinity.toFloat()) {
            with(density) { 220.dp.toPx() }
        } else {
            availableHeight
        }

        /** 초기 스크롤 위치를 계산하여 수행합니다. */
        LaunchedEffect(currentPickerHeightPx) {
            val targetIndex = items.indexOf(initialItem)
            /** initialItem이 items 내부에 존재하지 않아 targetIndex가 정수로 반환되지 않을 경우, 안전하게 0을 반환토록 설계합니다. */
            val safeTargetIndex = if (targetIndex >= 0) targetIndex else 0
            
            lastSelectedIndex = safeTargetIndex
            scrollState.scrollToItem(safeTargetIndex)
        }

        LazyColumn(
            modifier = Modifier.fillMaxSize(),
            state = scrollState,
            flingBehavior = rememberSnapFlingBehavior(scrollState),
            /** 양끝 값 또한 스크롤하여 선택할 수 있도록 상 하단에 (전체높이 - 단일 아이템 높이)/2 만큼 높이 패딩을 줍니다. */
            contentPadding = PaddingValues(vertical = with(density) {
                ((currentPickerHeightPx - itemHeightPx) / 2f).toDp()
            })
        ) {
            items(
                count = items.size,
                itemContent = { i ->
                    val item = items[i]

                    Row(
                        modifier = Modifier
                            .fillMaxWidth()
                            .height(itemHeight)
                            .onGloballyPositioned { coordinates ->
                                val y = (coordinates.positionInParent().y) + (itemHeightPx / 2f)
                                val parentHalfHeight = (currentPickerHeightPx / 2f)
                                val isCurrentlySelected = kotlin.math.abs(parentHalfHeight - y) <= (itemHeightPx / 2f)

                                if (isCurrentlySelected && lastSelectedIndex != i && item.isNotEmpty()) {
                                    onItemSelected(i, item)
                                    lastSelectedIndex = i
                                }
                            },
                        horizontalArrangement = Arrangement.Center,
                        verticalAlignment = Alignment.CenterVertically
                    ) {
                        content(item, lastSelectedIndex == i)
                    }
                }
            )
        }

        Box(
            modifier = Modifier
                .fillMaxWidth()
                .height(itemHeight)
                .drawWithContent {
                    drawRoundRect(
                        color = Gray20,
                        cornerRadius = CornerRadius(8.dp.toPx()),
                        blendMode = BlendMode.Multiply
                    )
                }
        )
    }
}

3.1. 고정 아이템 높이와 BoxWithConstraints

우선, 아이템 높이를 iOS 기준과 동일한 36dp 상수로 지정하였습니다. 아이템 고정높이에 대한 힌트를 얻을 수 있던 것은, 의외로 SwiftUI의 Picker였습니다.

초기 SwiftUI Picker를 사용하면서 item 내부 글자가 일정 크기를 넘어갈 경우, crop되는 이슈가 있어 답답함을 많이 느꼈었는데, SwiftUI의 Picker처럼 각 item의 높이값을 아예 고정하면, 높이 계산 로직으로 발생할 수 있는 변수를 최소화할 수 있습니다.

이후 SubcomposeLayout 대신, BoxWithConstraints의 maxHeight로 부모가 제공하는 영역을 측정했습니다. 이는 부모의 제약을 composition 시점에 재진입 없이 읽을 수 있게 해주기 때문에, 변수를 최소화합니다. 만약 상위에서 높이를 주지 않았다면 Constraints.Infinity가 들어오는데, 이때는 220.dp(36dp × 5개)를 상한으로 삼아 currentPickerHeightPx를 결정하도록 했습니다.

3.2. 더미 항목 → contentPadding 치환

기존 LaunchedEffect의 경우, scrollState.scrollToItem(safeTargetIndex)만 수행하도록 역할을 축소시켰으며, 문제의 원인이였던 더미 item 대신 세부 높이값을 직접 LazyColumn의 contentPadding으로 주입하여 양 끝 아이템을 선택할 수 있도록 했습니다.

3.3.포커스 판별의 단순화

더미 item을 제거하게 됨에 따라, onGloballyPositioned 내부에서의 포커스 판별 로직에서의 추가 계산 또한 제거하였습니다. onGloballyPositioned는 Drawing까지 진행이 되고 난 후에 호출되기에 실제 배치 결과를 기준으로 판별하기 때문입니다.

이렇게 렌더링 로직을 재설계하면서, 높이에 따른 제약을 최소화하고 다양한 폼팩터에서도 안정적인 포커싱을 보장할 수 있게 되었습니다.

4. 디테일 마감 작업

렌더링 구조가 안정화된 뒤에는 iOS 플랫폼 사용경험과 큰 차이를 느끼지 못하게 하는 것을 목표로 디테일을 다듬었습니다.

4.1. 리스트 상·하단에 페이드 스크림 추가

우선 중앙 하이라이트 박스는 그대로 유지하되, 리스트 상·하단에 두 개의 Box를 LazyColumn 위에 겹치고 각각 Brush.verticalGradient를 적용해 위쪽은 연한 하얀색→ 투명, 아래쪽은 투명 → 하얀색으로 그라데이션을 만들었습니다.

앞서 전달드렸듯 Compose는 재구성(recomposition) → 레이아웃(측정→배치) → 드로잉 순으로 진행됩니다. 때문에, 배치 이후 drawWithContent 단계에서 그라데이션 및 중앙 박스를 추가해 스크롤되는 리스트 위에 고정된 효과(하이라이트, 페이드)가 얹어질 수 있도록 했습니다.

4.2. 인접 아이템 탭 상호작용 시, 포커스 변경되도록 고도화

마지막으로, 인접 항목을 탭하면 즉시 포커스가 이동하도록 UX를 마감했습니다. 각 항목 Row에 pointerInput(i) 를 추가하고 detectTapGestures의 onTap 콜백에서 scrollState.animateScrollToItem(i)를 호출하도록 했습니다.

이때 rememberCoroutineScope()을 사용한 이유는 “이 컴포저블이 화면에 있는 동안만 유효한 코루틴 스코프”를 얻기 위해서입니다. 만일, ClobalScope 등을 통해 컴포저블의 생명주기와 불일치하게 코루틴을 호출할 경우, CancelledCoroutine 예외나 메모리 누수로 이어질 수 있습니다.

아이템 탭을 통해 위치가 변경되어도, 포커스 여부 판별에 핵심적인onGloballyPositioned를 트리거시키지 않는다면, 아무런 의미가 없을 것입니다. 다행히 animateScrollToItem 호출 시, Compose는 내부적으로 한 프레임(화면이 한번 그려지는 주기 = 통상 16ms)씩 위치를 갱신하면서 각 아이템의 실제 위치 또한 새로 계산됩니다. onGloballyPositioned는 배치가 끝난 직후마다 호출되는 콜백이기에 포커스 판별 로직에서도 엣지케이스를 고려할 필요가 없어집니다.

5. 최종 코드 및 결과물

// Wheel Picker
@Composable
fun WheelPicker(
    modifier: Modifier = Modifier,
    items: List<String>,
    initialItem: String,
    onItemSelected: (Int, String) -> Unit = { _, _ -> },
    content: @Composable ((String, Boolean) -> Unit)
) {
    val density = LocalDensity.current
    val scrollState = rememberLazyListState(0)
    var lastSelectedIndex by remember { mutableStateOf(0) }
    val coroutineScope = rememberCoroutineScope()

    val itemHeight = 36.dp
    val itemHeightPx = with(density) { itemHeight.toPx() }

    Column(modifier) {
        BoxWithConstraints(
            modifier = Modifier
                .fillMaxWidth()
                .drawWithContent {
                    drawContent()
                    val centerY = size.height / 2f
                    val rectTop = centerY - (itemHeightPx / 2f)
                    val rectHeight = itemHeightPx
                    drawRoundRect(
                        color = Gray20,
                        cornerRadius = CornerRadius(8.dp.toPx()),
                        blendMode = BlendMode.Multiply,
                        topLeft = Offset(0f, rectTop),
                        size = Size(size.width, rectHeight)
                    )
                },
            contentAlignment = Alignment.Center
        ) {
            val availableHeight = this.constraints.maxHeight.toFloat()
            val currentPickerHeightPx = if (availableHeight == Constraints.Infinity.toFloat()) {
                with(density) { 220.dp.toPx() }
            } else {
                availableHeight
            }

            LaunchedEffect(currentPickerHeightPx) {
                val targetIndex = items.indexOf(initialItem)
                val safeTargetIndex = if (targetIndex >= 0) targetIndex else 0

                lastSelectedIndex = safeTargetIndex
                scrollState.scrollToItem(safeTargetIndex)
            }

            val pickerHeightDp = with(density) { currentPickerHeightPx.toDp() }
            val fadeHeightDp =
                with(density) { ((currentPickerHeightPx - itemHeightPx) / 2f).toDp() }

            LazyColumn(
                modifier = Modifier
                    .fillMaxWidth()
                    .height(pickerHeightDp),
                state = scrollState,
                flingBehavior = rememberSnapFlingBehavior(scrollState),
                contentPadding = PaddingValues(vertical = fadeHeightDp)
            ) {
                items(
                    count = items.size,
                    itemContent = { i ->
                        val item = items[i]

                        Row(
                            modifier = Modifier
                                .fillMaxWidth()
                                .height(itemHeight)
                                .pointerInput(i) {
                                    detectTapGestures(
                                        onTap = {
                                            coroutineScope.launch {
                                                scrollState.animateScrollToItem(i)
                                            }
                                        }
                                    )
                                }
                                .onGloballyPositioned { coordinates ->
                                    val y = (coordinates.positionInParent().y) + (itemHeightPx / 2f)
                                    val parentHalfHeight = (currentPickerHeightPx / 2f)
                                    val isCurrentlySelected = abs(parentHalfHeight - y) <= (itemHeightPx / 2f)

                                    if (isCurrentlySelected && lastSelectedIndex != i && item.isNotEmpty()) {
                                        onItemSelected(i, item)
                                        lastSelectedIndex = i
                                    }
                                },
                            horizontalArrangement = Arrangement.Center,
                            verticalAlignment = Alignment.CenterVertically
                        ) {
                            content(item, lastSelectedIndex == i)
                        }
                    }
                )
            }

            Box(
                modifier = Modifier
                    .fillMaxWidth()
                    .height(fadeHeightDp)
                    .align(Alignment.TopCenter)
                    .drawWithContent {
                        drawRect(
                            brush = Brush.verticalGradient(
                                colors = listOf(White, White.copy(alpha = 0f))
                            )
                        )
                    }
            )

            Box(
                modifier = Modifier
                    .fillMaxWidth()
                    .height(fadeHeightDp)
                    .align(Alignment.BottomCenter)
                    .drawWithContent {
                        drawRect(
                            brush = Brush.verticalGradient(
                                colors = listOf(White.copy(alpha = 0f), White)
                            )
                        )
                    }
            )
        }
    }
}

// Wheel Picker 사용 화면
@Composable fun TestScreen() {
    val isLoading by viewModel.isLoading.collectAsState()

    var value by remember { mutableStateOf("5") }
    var isBottomSheetPresent by remember { mutableStateOf(false) }

    Column(
        modifier = Modifier
            .imePadding()
            .navigationBarsPadding(),
    ) {
        Spacer(modifier = Modifier.weight(1f))

        Box(
            modifier = Modifier
                .fillMaxWidth()
                .height(48.dp)
                .padding(horizontal = 32.dp)
                .border(width = 1.dp, color = Black, shape = RoundedCornerShape(size = 8.dp))
                .background(White),
            contentAlignment = Alignment.Center
        ) {
            Text(
                text = value,
                style = HMFont.subhead3,
                color = Black,
                modifier = Modifier.padding(horizontal = 16.dp)
            )
        }

        Spacer(modifier = Modifier.weight(1f))

        HMPicker(
            modifier = Modifier
                .height(420.dp)
                .padding(horizontal = 16.dp),
            items = (40 downTo 1).map { it.toString() },
            initialItem = value,
            onItemSelected = { index, selectedValue ->
                value = selectedValue
            }
        )
        { item, isSelected ->
            if (item.toString().isNotEmpty()) {
                Text(
                    text = item.toString(),
                    modifier = Modifier.padding(end = 4.dp),
                    color = if (isSelected) Black else Grey,
                )

                Text(
                    text = "단위",
                    color = if (isSelected) Black else Grey,
                )
            }
        }
    }
}

6. 결론

• Compose 파이프라인을 다시 정리할 수 있었습니다. SubcomposeLayout이 측정 단계에 끼어드는 순간 상태 타이밍이 얼마나 복잡해지는지 경험했고, BoxWithConstraints + 고정 높이 조합으로 구조를 단순화하면 재배치·재구성 오버헤드를 크게 줄일 수 있다는 사실을 체감할 수 있었습니다.
• onGloballyPositioned처럼 배치 이후 호출되는 콜백을 중심에 두면, 스크롤/애니메이션 방식이 달라져도 동일한 포커스 판별 로직을 재사용할 수 있다는 점을 확인했습니다.