feat(ActionArea): 4.0.0 스펙 업데이트 (캡션 아이콘·backgroundColor·Divider·여백)

[claude]

Requested by 김삼열 · Slack thread

개요

• 이슈 링크 : WRP-2462
• base 브랜치: release/4.0.0
• Figma 상세

수정사항

항목	내용
Divider 색	lineNeutralSecondary → lineNeutralTertiary (Line/Normal/Alternative 대응)
캡션 타이포	.label2 Regular → Medium. 색(foregroundNeutralTertiary)은 유지
Extra 여백	top 20 / horizontal 24 / bottom 20 (기존 top 20 / horizontal 20 / bottom 24)
캡션 아이콘	caption(_:icon:) 신설. 기본값 nil(꺼짐), 16×16, 텍스트와 간격 4, 세로 가운데 정렬, 색은 캡션과 동일
배경색	backgroundColor(_:) 신설. 미지정 시 surfaceElevatedPrimary, 지정한 색은 sticky 그라데이션 시작색으로도 함께 적용

대체 액션 Button color(.primary → .assistive)는 이번 범위에서 제외했습니다.

공개 API

// 모디파이어
.caption(_ caption: String?, icon: Icon? = nil)
.backgroundColor(_ backgroundColor: SwiftUI.Color?)

// ActionArea.Model 두 이니셜라이저 / View.actionArea(...) 두 오버로드
caption: String? = nil,
captionIcon: Icon? = nil,
backgroundColor: SwiftUI.Color? = nil

기존 호출부는 모두 기본값을 쓰므로 동작 변화가 없습니다(source-compatible). 단, 캡션 타이포·Divider 색·Extra 여백은 의도된 시각 변경입니다.

변경 파일

• Sources/Montage/1 Components/2 Actions/ActionArea.swift
• Sources/Blueprint/Sources/Scene/Previews/ActionAreaPreview.swift — captionIcon / backgroundColor 옵션 추가, 색상은 ColorPickerOptionRow로 선택
• Sources/Blueprint/Sources/Utilities/PreviewLayout.swift — .upsideDown 모드에서 미리보기 본문을 edge-to-edge로 (기존 주석에 적힌 의도대로). ActionArea 배경·그라데이션이 화면 폭을 채우지 못하던 문제 수정
• documentation/, packages/montage-mcp/data/components.json — make 재생성

검증

• iPhone 17 Pro(iOS 26.3) 시뮬레이터에서 Blueprint 실행 확인
  • 캡션 아이콘 노출·정렬·간격, Extra 좌우 24pt 여백, Divider(다크 22%), 커스텀 배경색 + 그라데이션, transparency 전환
• make 실행 후 문서/MCP 데이터 재생성 커밋 (verify-docs 대응)

확인 필요

• Extra 하단 여백: 지라 본문은 bottom 24 → 20, Figma 상세는 하단 4 → 0입니다. Figma의 "변경 전"(좌우 20 / 상단 24 / 하단 4)이 iOS 코드(top 20 / horizontal 20 / bottom 24)와 맞지 않아 다른 기준으로 보여, iOS 코드를 직접 인용한 지라 값(20) 을 따랐습니다. 디자이너 확인 부탁드립니다.
• captionIcon을 Model·actionArea(...)에도 노출했습니다. 티켓에 명시된 건 아니지만 backgroundColor가 두 경로에 다 있어 비대칭을 피했습니다.
• Figma의 compact variant는 iOS Variant(strong/neutral/cancel)에 없어 해당 없음으로 두었습니다.

---

추가 수정: ActionArea.Model 적용 로직 중앙화

Model → ActionArea 적용을 네 소비자(actionArea(...) 모디파이어 · TopNavigation · Popup · BottomSheet)가 각자 손으로 재구현하고 있었습니다. 그래서 이번에 Model에 추가한 captionIcon·backgroundColor가 모디파이어 외 세 곳에서 조용히 무시됐습니다. Model은 public이고 TopNavigation(withBottom:)·modalActionArea(_:)가 이를 받으므로 호출부가 지정할 수 있는데 아무 일도 일어나지 않는 상태였습니다.

ActionArea.Model에 공유 헬퍼를 두고 네 소비자가 모두 경유하도록 했습니다.

extension ActionArea.Model {
    func makeActionArea(transparentBackground: Bool) -> ActionArea
    func resolvedTransparentBackground(automatic: Bool) -> Bool
}

투명도는 해소된 Bool로 받습니다. 소비자마다 해소 방식이 다르기 때문입니다(스크롤 컨테이너 소유 여부). 각 소비자가 기존에 하던 계산을 그대로 유지해 동작 변화가 없습니다.

소비자	투명도 해소	회귀 확인
actionArea(...)	.automatic → 신호 없어 false (현행 유지)	✅
TopNavigation	.automatic → scrollStatus.scrolledToMax	✅
Popup	기존 backgroundTransparency(for:) 헬퍼	✅
BottomSheet	scrollStatus.scrolledToMax (control 미참조, 현행 유지)	✅

iPhone 17 Pro(iOS 26.3) 시뮬레이터에서 네 경로 모두 렌더·그라데이션 페이드를 확인했습니다. make 결과 문서/MCP 데이터 변경 없음(공개 API 시그니처 불변).

후속 티켓 후보 (이 PR 범위 밖)

1. 투명도 API 정리 — transparentBackground(_:) / BackgroundTransparencyControl / backgroundTransparency: 제거하고 스크롤 신호에서 파생. 상위 앱 호출부 3건 조사 완료(모두 대체 가능, 그중 1건은 이미 죽은 인자). .automatic 미구현(모디파이어 경로) · BottomSheet의 control 미참조 · 죽은 isManual도 함께 정리
2. Model → ViewBuilder 슬롯 전환 — 구성 API 이중화(체인 vs Model) 해소. 이번 결함의 근본 원인
3. ScreenScaffold 추출 — 상단 바/콘텐츠/하단 액션 3단 배치를 한곳으로. 모디파이어 사용과 직접 조립의 동작 차이 제거