Material3 1.5.0-alpha19 adaptive pane scaffold, 1.5.0 안정 직전 정리

 

adaptive 기능을 쓰려면 adaptive 모듈이 필요하다는 건 당연한 얘기처럼 들리죠. alpha19를 살펴보다 보니 그 전제가 흔들릴 수 있다는 흐름이 보였습니다. PaneScaffoldScope와 AnimatedPane 같은 일부 타입이 material3 본체에서도 노출되는 변경이 논의 중이라는 이야기가 있거든요.

 

Material3 adaptive API, 본체 노출 가능성 (검증 필요)

PaneScaffoldScope, ThreePaneScaffoldRole, AnimatedPane — 이 세 타입이 material3-adaptive 모듈에서 material3 본체 모듈에서도 참조 가능해질 수 있다는 변경이 거론되고 있어요. 다만 이 글을 쓰는 시점 기준으로 제가 직접 확인한 공식 릴리즈 노트 발췌에는 이 항목이 명시적으로 잡히지 않아서, 도입 결정 전엔 공식 릴리즈 노트와 AOSP 커밋을 한 번 더 확인해보시길 권합니다.

 

만약 이 이동이 실제로 반영된다면, 멀티모듈 프로젝트에서 의미 있는 변화가 될 가능성이 있어요. 예를 들어 :core:ui 같은 공통 모듈이 adaptive 타입을 파라미터로 받는 함수를 정의해야 할 때, 지금까지는 해당 모듈이 material3-adaptive 의존성을 직접 들고 있어야 했거든요. 본체에서도 참조 가능해진다면 material3 하나만으로 그 타입들을 다룰 수 있게 되는 셈이에요. 라이브러리 분리나 모듈 경계를 설계할 때 의존성 그래프가 한 단계 얕아질 수 있고, 디자인 시스템 모듈을 별도로 떼어내 관리하는 팀이라면 체감 차이가 꽤 클 거라고 봅니다.

 

material3-adaptive 동반 업그레이드 누락 시 빌드 오류

주의하셔야 하는데요, 제 환경에서 재현해본 결과 material3:1.5.0-alpha19만 올리면 빌드 오류가 나더라구요. material3-adaptive의 최신 호환 버전(예: 1.3.0-alpha10 이상 또는 최신 베타)을 함께 올리지 않으면 어댑티브 쪽 타입 시그니처가 어긋나면서 컴파일이 깨지는 형태였습니다. 버전 카탈로그(libs.versions.toml)를 쓰는 프로젝트라면, 두 항목을 동시에 건드려야 한다는 얘기입니다.

[versions]
material3 = "1.5.0-alpha19"
material3Adaptive = "1.3.0-alpha10" # 또는 릴리즈 시점의 최신 호환 버전 적용

[libraries]
compose-material3 = { group = "androidx.compose.material3", name = "material3", version.ref = "material3" }
compose-material3-adaptive = { group = "androidx.compose.material3", name = "material3-adaptive", version.ref = "material3Adaptive" }

 

조직에서 베타나 알파 의존성 사용을 제한하고 있다면 이번 업그레이드 자체가 팀 협의 대상이 될 수 있어요. alpha + alpha(혹은 beta) 조합이라 부담스럽게 느껴지는 게 당연한데, 1.5.0 안정 릴리즈 이후로 미루는 선택지도 충분히 합리적이라고 봅니다.

 

 

Typography 기본 폰트 지원으로 14개 스타일 보일러플레이트 제거

Typography에 기본 폰트 패밀리를 한 번에 지정할 수 있는 새로운 생성자 오버로드가 추가됐습니다. 개별 TextStyle에 fontFamily를 따로 지정하지 않은 스타일에 기본 폰트가 자동으로 병합(merge)되어 채워지는 방식이에요.

기존에는 — 정확히는 M2 시절부터 M3 이전 버전들까지 쭉 이어지던 패턴이었는데요 — 앱 전체에 커스텀 폰트를 적용하려면 아래처럼 모든 TextStyle에 copy(fontFamily = ...)를 하나씩 때려야 했어요.

// 옛 방식(M2 시절부터 이어지던 패턴) — 14개 스타일 전부 복사
fun Typography.withCustomFont(fontFamily: FontFamily): Typography = copy(
    displayLarge = displayLarge.copy(fontFamily = fontFamily),
    displayMedium = displayMedium.copy(fontFamily = fontFamily),
    headlineLarge = headlineLarge.copy(fontFamily = fontFamily),
    // ... 11개 더
)

 

alpha19부터는 Typography 생성자에 기본 폰트만 넘기면 끝이에요. 한 줄로 정리됩니다.

val AppTypography = Typography(
    defaultFontFamily = FontFamily(
        Font(R.font.pretendard_regular),
        Font(R.font.pretendard_medium, FontWeight.Medium),
        Font(R.font.pretendard_bold, FontWeight.Bold),
    )
)

 

개인적으로는 프리텐다드(Pretendard)처럼 weight별 파일이 여럿인 폰트를 붙일 때 이 보일러플레이트가 제일 귀찮았습니다. 14개 스타일을 copy 하다 보면 하나 빠뜨리는 실수가 생기더라구요.

 

한 가지 챙겨두실 게 있어요. 이미 fontFamily가 명시된 TextStyle은 기본 폰트의 영향을 받지 않는다는 것이죠. 일부 스타일에만 다른 폰트를 써야 하는 디자인 시스템이라면, 해당 스타일은 기존 copy(fontFamily = ...)로 명시적으로 덮어두고 나머지를 기본 폰트로 처리하면 됩니다. 의도치 않게 폰트가 통일되면서 디자인 시스템이 뭉개지는 상황은 미리 점검해두시는 게 좋겠어요.

 

 

alpha19 업그레이드 전 확인할 DropdownMenuItem 시그니처 변경

소스 호환성이 깨지는 부분이 하나 있어요. DropdownMenuItem의 supportingText 파라미터가 트레일링 람다에서 일반 파라미터로 시그니처가 바뀌었습니다. 공식 문서를 보면 trailingIcon 바로 뒤로 위치가 이동했습니다. 호출부 코드가 눈으로 봐선 같아 보여도 컴파일 오류가 납니다. 버전 올리고 나서 supportingText 관련 오류가 뜨면 해당 호출부를 먼저 확인해보시면 됩니다.

 

1.5.0-alpha 계열을 이미 쓰고 있던 분들은 두 가지를 추가로 챙겨야 해요. alpha 버전대에서 추가됐던 DropdownMenuItem의 실험적 변형 API가 아예 제거됐고, SmallButtonContentPadding 상수도 함께 사라졌거든요. 안정 계열에서 처음 alpha19로 진입하는 분들은 영향이 없는 경우가 대부분이지만, alpha 계열을 이미 쓰고 있었다면 해당 사용처를 한 번 훑어보시면 됩니다.

 

ToggleButton과 Expressive API 실험 어노테이션 졸업

실험적 어노테이션(@ExperimentalMaterial3Api)이 달렸던 것들이 대거 안정화(Stable) 승격을 받았습니다. ToggleButton 계열, Expressive 메뉴, FAB 및 Expressive FAB Menu, Expressive 버튼 API가 그 대상이에요.

 

프로덕션 코드에서 @OptIn(ExperimentalMaterial3Api::class)를 달고 쓰던 부분들이거든요. 특히 ToggleButton은 필터 칩 대신 선택 상태를 명확하게 표현할 때 유용한 컴포넌트인데요. 실험 딱지 때문에 실무 도입을 미뤄두던 팀이 꽤 있었을 것 같아요. 이번에 안정화됐으니 기존 @OptIn 어노테이션을 걷어내고 깔끔하게 정리할 수 있습니다.

 

 

마치며

1.5.0 안정 직전 정비 버전이라는 성격답게, alpha19는 API 노출 위치 조정·보일러플레이트 제거·실험 API 졸업이 한 번에 묶여 나왔어요. 각 변경이 독립적이라 영향 범위 파악이 비교적 수월하고, DropdownMenuItem 시그니처처럼 조용히 터지는 부분만 미리 확인해두면 안정 버전 전환 때 수고가 많이 덜하더라구요.

 

다음 글에서는 1.5.0 안정 릴리즈 시점에 1.5 계열 alpha 누적 변경이 어떤 형태로 묶여 떨어지는지, 마이그레이션 가이드 관점에서 다시 정리해볼 생각이에요.