Antigravity Agent
3.9 KiB
3.9 KiB
Component API Design
📌Brief 소목 Summary
컴포넌트 API 디자인(Component API Design)은 개발자가 UI 컴포넌트를 사용하고 구성하는 방식에 대한 구조적 설계와 인터페이스 정의를 의미합니다[1-3]. 잘 설계된 컴포넌트 API는 과도한 Prop 설정에 의존하는 대신 합성(Composition)을 활용하여 소비자가 유연하게 UI를 조립할 수 있도록 돕습니다[2, 4]. 이는 확장 가능하고 유지보수가 쉬운 재사용 가능한 React 컴포넌트 라이브러리를 구축하는 데 핵심적인 역할을 합니다[1, 5, 6].
📖 Core Content
- Prop-Driven API의 한계: 컴포넌트의 레이아웃과 동작을 오직 수많은 Prop(예: 다수의 불리언 플래그)으로만 제어하려 하면, 각 Prop이 결합되어 내부 로직이 복잡해지는 '블랙박스'가 형성됩니다[4, 7, 8]. 이는 예기치 않은 동작을 유발하고, 사소한 변경에도 시스템이 쉽게 깨지는 원인이 됩니다[4, 7].
- 명확한 계약(Explicit Contracts) 및 Prop 설계: 좋은 컴포넌트 API는 직관적이고 오용하기 어려워야 합니다[3]. 구현 방식이 아닌 사용 목적(intent)에 따라 Prop 이름을 짓고, Prop의 수를 최소화하여 지나치게 복잡한 설정(Prop Soup)을 피해야 합니다[3, 9]. 또한 초기 사용을 위해 합리적인 기본값(Sensible Defaults)을 제공해야 합니다[3, 10].
- 합성 기반(Composition-Driven) 사고의 전환: "컴포넌트가 어떻게 보여야 하는지"를 지시하는 대신, 상태와 규칙만 제공하고 "레이아웃은 소비자가 조립"하도록 구성하는 멘탈 모델로의 전환이 필요합니다[2].
- 확장 가능한 주요 API 패턴:
- 복합 컴포넌트 (Compound Components):
Accordion,Accordion.Item등과 같이 여러 하위 컴포넌트가 React Context를 통해 암시적으로 상태를 공유하는 패턴입니다[5, 11, 12]. 이 패턴은 Prop 드릴링을 방지하고 선언적이며 읽기 쉬운 구조를 제공합니다[5, 11]. - Render Props: 사용자에게 특정 UI 렌더링에 대한 완전한 제어권을 넘겨주는 '탈출구(escape hatch)' 역할을 하며, 기존 API를 해치지 않으면서 고급 사용자에게 유연성을 제공합니다[13, 14].
- 오버라이드 패턴 (Overrides Pattern): Uber의 Base Web 등에서 활용되는 방식으로,
overridesprop을 통해 컴포넌트 내부의 특정 하위 요소에 접근하여 속성, 스타일, 또는 렌더링 방식 전체를 대체할 수 있게 해줍니다[9, 15-17]. 이를 통해 모든 엣지 케이스를 위한 새로운 Prop을 추가할 필요가 없어집니다[17]. - 헤드리스 컴포넌트 (Headless Components) 및 슬롯 (Slots): UI 스타일링 없이 상태와 동작 로직만 제공하거나(Headless), 소비자가 자체 콘텐츠를 삽입할 수 있는 의도된 영역(Slots)을 제공하여 API의 복잡성을 낮추는 패턴입니다[8, 18].
- 복합 컴포넌트 (Compound Components):
🔗 Knowledge Connections
- Related Topics: Compound Components, Headless Components, Overrides Pattern, Prop Drilling, Atomic Design
- Projects/Contexts: Uber Base Web, Radix UI, Shopify Polaris
- Contradictions/Notes: 복합 컴포넌트(Compound Components) 패턴은 강력한 구성의 자유도를 제공하지만, 지나친 자유로움으로 인해 사용자가 하위 컴포넌트의 순서를 임의로 변경하여 UX나 접근성의 일관성을 해칠 위험이 있습니다[19, 20]. 따라서 버튼이나 아이콘같이 단순하고 구조가 고정된 컴포넌트에서는 불필요한 추상화가 되므로 일반적인 Prop-Driven 방식이 더 안전하고 적합합니다[20, 21].
Last updated: 2026-04-26