@croquiscom/pds 16.57.0 → 16.57.1

package/pds-skills/resources/guides/guide-composition-patterns.md

@@ -0,0 +1,537 @@
+# PDS 합성 패턴 가이드
+
+PDS를 사용하는 에이전트가 TypeScript type/JSDoc만으로는 파악하기 어려운 컴포넌트 합성 제약과 잘못된 사용 패턴을 8개 클래스로 정리한다.
+
+> **이 가이드에 없는 것**: prop 이름, optional/required 여부, default value, type. 이런 정보는 `*.props.txt` 파일의 Props 표에서 읽어라. 이 가이드는 type/JSDoc만으로 자명하지 않은 _합성 규칙_만 다룬다.
+
+---
+
+## 클래스 #1 — Flat API (dot-notation 없음)
+
+### 무엇이 문제인가
+
+React 컴포넌트 라이브러리 중 일부(Radix UI, ShadCN, Chakra 등)는 `\<Modal.Body\>`, `\<Menu.Item\>`, `\<Tabs.Tab\>` 같은 dot-notation compound 패턴을 쓴다. PDS는 이 패턴을 **사용하지 않는다**. 자식 컴포넌트는 항상 별도의 named export다.
+
+### 잘못된 패턴
+
+```tsx
+// ❌ dot-notation — PDS에 없는 export
+<Modal.Body>내용</Modal.Body>
+<Modal.Footer>버튼</Modal.Footer>
+<Menu.Item id="foo" label="Foo" />
+<LineTabs.Tab id="tab1">탭1</LineTabs.Tab>
+<BoxTabs.Tab id="tab1">탭1</BoxTabs.Tab>
+```
+
+### 올바른 PDS 패턴
+
+```tsx
+// ✅ 별도 named export 사용
+import { Menu, MenuItem, MenuGroup } from '@croquiscom/pds';
+<Menu>
+  <MenuItem id='menu-item-1' label='메뉴 1' />
+  <MenuGroup id='group-1' label='그룹'>
+    <MenuItem id='menu-item-2' label='메뉴 2' />
+  </MenuGroup>
+</Menu>;
+// ✅ LineTabs + LineTab
+import { LineTabs, LineTab } from '@croquiscom/pds';
+<LineTabs activeTabId={activeTab} onChange={setActiveTab}>
+  <LineTab id='tab1'>탭 1</LineTab>
+  <LineTab id='tab2'>탭 2</LineTab>
+</LineTabs>;
+// ✅ BoxTabs + BoxTab
+import { BoxTabs, BoxTab } from '@croquiscom/pds';
+<BoxTabs activeTabId={activeTab} onChange={setActiveTab}>
+  <BoxTab id='tab1'>탭 1</BoxTab>
+  <BoxTab id='tab2'>탭 2</BoxTab>
+</BoxTabs>;
+```
+
+### 실제 컴포넌트 코드 근거
+
+`src/components/menu/index.ts`, `src/components/tabs/index.ts`를 보면 `Menu`, `MenuItem`, `MenuGroup`, `LineTabs`, `LineTab`, `BoxTabs`, `BoxTab`, `PanelTabs`, `PanelTab`, `PanelTabGroup`이 각각 별도 named export로 등록되어 있다. `Modal.Body` 같은 static property로 붙여 둔 하위 컴포넌트는 소스 어디에도 없다.
+
+---
+
+## 클래스 #2 — requiredParent (context throw)
+
+### 무엇이 문제인가
+
+일부 PDS 컴포넌트는 특정 부모 컴포넌트의 Context 없이 단독으로 사용하면 런타임 오류가 발생한다. TypeScript 타입은 이 제약을 표현하지 못한다.
+
+### 잘못된 패턴
+
+```tsx
+// ❌ LineTab을 LineTabs 밖에서 사용 → "LineTabContext is not defined"
+<div>
+  <LineTab id="tab1">탭 1</LineTab>
+</div>
+// ❌ MenuItem을 Menu 밖에서 사용 → "MenuContext is not defined"
+<div>
+  <MenuItem id="item1" label="아이템" />
+</div>
+// ❌ BoxTab을 BoxTabs 밖에서 사용 → "BoxTabContext is not defined"
+<BoxTab id="tab1">탭</BoxTab>
+// ❌ PanelTab을 PanelTabs 밖에서 사용 → "PanelTabContext is not defined"
+<PanelTab id="tab1" title="탭" />
+```
+
+### 올바른 PDS 패턴
+
+| 자식 컴포넌트 | 필수 부모 | 오류 메시지 | | ----------------------- | ----------- | -------------------------------- | | `LineTab` | `LineTabs` | `LineTabContext is not defined` | | `BoxTab` | `BoxTabs` | `BoxTabContext is not defined` | | `PanelTab` | `PanelTabs` | `PanelTabContext is not defined` | | `MenuItem`, `MenuGroup` | `Menu` | `MenuContext is not defined` |
+
+`PanelTabGroup`은 context를 직접 소비하지 않아 단독 사용이 가능하지만, `PanelTabs` 안에서 그룹화 역할로 쓰는 것이 설계 의도다(`src/components/tabs/PanelTabs/PanelTabGroup.tsx` 확인).
+
+```tsx
+// ✅ 항상 부모 컴포넌트 안에서 사용
+<LineTabs activeTabId={activeTab} onChange={setActiveTab}>
+  <LineTab id="tab1">탭 1</LineTab>
+  <LineTab id="tab2">탭 2</LineTab>
+</LineTabs>
+<Menu>
+  <MenuItem id="item1" label="아이템 1" />
+  <MenuItem id="item2" label="아이템 2" />
+</Menu>
+<PanelTabs activeTabId={activeTab} onChange={setActiveTab}>
+  <PanelTabGroup title="그룹">
+    <PanelTab id="tab1" title="탭 1" number={3} suffix="건" />
+  </PanelTabGroup>
+</PanelTabs>
+```
+
+---
+
+## 클래스 #3 — Portal 위치 (FloatingPortal)
+
+### 무엇이 문제인가
+
+일부 PDS 컴포넌트는 `FloatingPortal`을 통해 `document.body`가 아닌 `id="pds-floating-root"` DOM 노드에 렌더링된다. 이 노드가 없으면 컴포넌트가 `document.body`에 폴백 렌더링될 수 있다.
+
+에이전트가 이 동작을 모르고 z-index 조정이나 CSS overflow 처리 시 "팝업이 특정 컨테이너 밖으로 나온다"는 예상 동작을 이해하지 못하는 경우가 있다. Portal 노드를 수동으로 생성하려 하거나, `FloatingTree`를 추가로 선언해야 한다고 오해하는 경우도 있다.
+
+### Portal 사용 컴포넌트 목록
+
+| 컴포넌트 | Portal 동작 | | -------------------------------------------------------------------------- | ---------------------------------------------------------------- | | `Modal` (BasicModal, AlertModal, ConfirmModal, NoticeModal, FloatingModal) | `pds-floating-root`에 렌더링. `FloatingTreeContext` 래핑 | | `BottomSheet` | `pds-floating-root`에 렌더링. `noUsePortal=true`로 비활성화 가능 | | `Drawer` | `pds-floating-root`에 렌더링. `noUsePortal=true`로 비활성화 가능 | | `Popover` | `pds-floating-root`에 렌더링 | | `Tooltip` | `pds-floating-root`에 렌더링 | | `Dropdown`, `DropdownFilter`, `DropdownInput` | 옵션 목록이 `pds-floating-root`에 렌더링 | | `DropdownComposite` | 옵션 목록이 `pds-floating-root`에 렌더링 | | `DatePicker` | 캘린더 패널이 `pds-floating-root`에 렌더링 | | `TimePicker`, `TimeRangePicker` | 시간 선택 패널이 `pds-floating-root`에 렌더링 | | `ColorPicker` | 컬러 팔레트가 `pds-floating-root`에 렌더링 |
+
+### 올바른 PDS 패턴
+
+```tsx
+// ✅ pds-floating-root 노드를 앱 루트에 추가 (없으면 document.body에 폴백)
+// index.html 또는 앱 초기화 파일에:
+<div id="pds-floating-root" />
+// ✅ Modal 사용 시 별도 FloatingTree 선언 불필요
+// Modal, BottomSheet, Drawer는 FloatingTreeContext로 래핑되어 내부에서 자동 처리
+import { Modal } from '@croquiscom/pds';
+<Modal opened={isOpen} onCancel={handleClose} title="제목">
+  {/* 내용 */}
+</Modal>
+// ✅ noUsePortal: 특정 컨테이너 안에 렌더링해야 할 때
+<BottomSheet opened={isOpen} noUsePortal>
+  {/* document.body 대신 현재 DOM 트리 안에 렌더링 */}
+</BottomSheet>
+```
+
+### 실제 컴포넌트 코드 근거
+
+`src/constants/floating.ts`의 `FLOATING_ROOT_ID = 'pds-floating-root'` 상수를 `BottomSheet.tsx`, `Drawer.tsx`, `ModalOverlay.tsx`, `Popover.tsx`, `Tooltip.tsx`, `DropdownOptions.tsx` 등이 `FloatingPortal`에 전달한다.
+
+---
+
+## 클래스 #4 — asChild 패턴 (Radix Slot)
+
+### 무엇이 문제인가
+
+Button 계열 컴포넌트에는 `asChild` prop이 있다. `asChild=true`로 설정하면 `\<button\>` DOM 요소를 렌더링하지 않고 children의 단일 ReactElement에 모든 props와 이벤트 핸들러를 전달한다(Radix Slot 패턴).
+
+에이전트가 이 패턴을 모르고 `\<a\>` 태그 링크 버튼을 만들 때 `\<Button\>` 안에 `\<a\>`를 중첩(button 안의 a — HTML 비유효)하는 경우가 있다. 커스텀 컴포넌트에 버튼 스타일을 적용하는 방법을 찾지 못하는 경우도 있다.
+
+### asChild 지원 컴포넌트
+
+`Button`, `TextButton`, `IconButton`, `FloatingButton`, `AccordionButton`, `PopoverButton`
+
+### 잘못된 패턴
+
+```tsx
+// ❌ button 안에 a 중첩 (HTML 유효성 오류)
+<Button kind="primary">
+  <a href="/dashboard">대시보드</a>
+</Button>
+// ❌ 클릭 이벤트를 div에 별도로 달고 Button 스타일을 흉내냄
+<div onClick={handleClick} style={{ ... }}>버튼처럼 보이는 div</div>
+```
+
+### 올바른 PDS 패턴
+
+```tsx
+// ✅ asChild=true: <a>가 <button>을 대체. Button의 모든 스타일과 props가 <a>에 적용됨
+<Button asChild kind="primary">
+  <a href="/dashboard">대시보드</a>
+</Button>
+// ✅ Next.js Link와 함께 사용
+import Link from 'next/link';
+<Button asChild kind="primary">
+  <Link href="/dashboard">대시보드</Link>
+</Button>
+// ✅ TextButton + asChild
+<TextButton asChild kind="link">
+  <a href="https://example.com" target="_blank">외부 링크</a>
+</TextButton>
+// ✅ IconButton + asChild (aria-label 유지)
+<IconButton asChild aria-label="닫기">
+  <button type="button" onClick={handleClose}><IconX /></button>
+</IconButton>
+```
+
+> **주의**: `asChild=true` 시 children은 반드시 단일 ReactElement여야 한다. Fragment(`\<\>`)나 여러 요소를 전달하면 Slot이 올바르게 작동하지 않는다.
+
+### 실제 컴포넌트 코드 근거
+
+`src/components/button/Button.tsx:71` — `const Comp = asChild ? Slot : 'button';` `src/components/button/types.ts:20` — `asChild?: boolean;` `@radix-ui/react-slot`의 `Slot` 컴포넌트를 사용한다.
+
+---
+
+## 클래스 #5 — directChildInjection (FormField의 cloneElement)
+
+### 무엇이 문제인가
+
+`FormField`는 `status` prop을 **React Context가 아니라 `cloneElement`로** 직접 자식에 주입한다. 이 메커니즘은 children이 Fragment(`\<\>`) 또는 래퍼 div 안에 있으면 작동하지 않는다.
+
+에이전트가 이 제약을 모르고 children을 Fragment나 래퍼로 감싸는 경우가 있다. `DatePicker` 같이 주입 대상이 아닌 컴포넌트도 자동으로 status를 받는다고 가정하는 경우도 있다.
+
+### status 자동 주입 대상 컴포넌트
+
+`Input`, `Dropdown`, `DropdownInput`, `NumericInput` (총 4개)
+
+### 잘못된 패턴
+
+```tsx
+// ❌ Fragment로 감싸면 cloneElement가 작동하지 않음
+<FormField status="error" label="이름">
+  <>
+    <Input placeholder="이름 입력" />
+  </>
+</FormField>
+// ❌ 래퍼 div 안에 있으면 주입되지 않음
+<FormField status="error">
+  <div>
+    <Input placeholder="이름" />
+  </div>
+</FormField>
+// ❌ DatePicker는 자동 주입 대상이 아님
+<FormField status="error">
+  <DatePicker value={date} onChange={setDate} />
+  {/* FormField의 status가 DatePicker에 전달되지 않음 */}
+</FormField>
+```
+
+### 올바른 PDS 패턴
+
+```tsx
+// ✅ 단일 직접 자식으로 사용해야 cloneElement가 작동
+<FormField status="error" label="이름" formHelperText="필수 항목입니다">
+  <Input placeholder="이름 입력" />
+</FormField>
+// ✅ Dropdown도 단일 직접 자식
+<FormField status="error" label="카테고리">
+  <Dropdown options={options} value={value} onChange={setValue} />
+</FormField>
+// ✅ DatePicker: 자체 error prop을 직접 전달해야 함
+<FormField status="error" label="날짜" formHelperText="날짜를 선택하세요">
+  <DatePicker
+    error
+    value={date}
+    onChange={setDate}
+  />
+</FormField>
+```
+
+### 실제 컴포넌트 코드 근거
+
+`src/components/form/FormField.tsx:60–80` —
+
+```javascript
+const hasStatusPropsComponent = (children) =>
+  isValidElement(children) && [Input, Dropdown, DropdownInput, NumericInput].includes(children.type);
+const clonedChildren = status && hasStatusPropsComponent(children) ? cloneElement(children, { status }) : children;
+```
+
+---
+
+## 클래스 #6 — renderForbidden (Hook-only API)
+
+### 무엇이 문제인가
+
+`Toast`와 `Notification`은 JSX 선언형 렌더링이 **금지**된다. TypeScript 타입 정의가 있고 Storybook에도 등장하지만, 이는 내부 구조 문서화용이지 직접 렌더링을 허용하는 것이 아니다.
+
+에이전트가 `\<Toast content="..." /\>` 또는 `\<Notification title="..." /\>`를 JSX로 직접 렌더링하는 코드를 작성하는 경우가 있다.
+
+### 잘못된 패턴
+
+```tsx
+// ❌ Toast JSX 직접 렌더링 금지
+import { Toast } from '@croquiscom/pds';
+return <Toast content='저장되었습니다.' kind='success' />;
+// ❌ Notification JSX 직접 렌더링 금지
+import { Notification } from '@croquiscom/pds';
+return <Notification title='알림' content='처리 완료' />;
+```
+
+### 올바른 PDS 패턴
+
+```tsx
+// ✅ Toast: useToast() Hook으로만 사용
+import { useToast } from '@croquiscom/pds';
+const MyComponent = () => {
+  const toast = useToast();
+  const handleSave = async () => {
+    await saveData();
+    toast.show({
+      content: '저장되었습니다.',
+      kind: 'success',
+      duration: 3000,
+    });
+  };
+  return <Button onClick={handleSave}>저장</Button>;
+};
+// ✅ Notification: useNotification() Hook으로만 사용
+import { useNotification } from '@croquiscom/pds';
+const MyComponent = () => {
+  const notification = useNotification();
+  const handleAction = async () => {
+    await processAction();
+    notification.show({
+      title: '처리 완료',
+      content: '작업이 성공적으로 처리되었습니다.',
+    });
+  };
+  return <Button onClick={handleAction}>실행</Button>;
+};
+```
+
+> **내부 동작**: `Toast`와 `Notification`은 `MessageManager`가 관리하는 별도 DOM에 주입된다. `useToast()`/`useNotification()`은 컴포넌트 함수 바디 최상위에서 호출해야 한다 (React Hook 규칙).
+
+### 실제 컴포넌트 코드 근거
+
+`src/components/toast/Toast.stories.tsx`의 주석(삭제 전):
+
+> "`\<Toast\>` JSX 직접 렌더링 금지. `useToast()` Hook 전용 API."
+
+`src/components/notification/Notification.stories.tsx`의 주석(삭제 전):
+
+> "`\<Notification\>` JSX 직접 렌더링 금지. `useNotification()` Hook 전용 API."
+
+---
+
+## 클래스 #7 — Named Slot Props (명시적 슬롯)
+
+### 무엇이 문제인가
+
+일부 PDS 컴포넌트는 `ReactNode` 타입의 named prop을 "슬롯"으로 사용한다. 타입은 prop 이름과 `ReactNode` 타입을 보여주지만, _어떤 prop이 슬롯이고 어떤 UI 영역을 교체하는지_는 타입만으로 자명하지 않다.
+
+슬롯을 모르는 에이전트가 `children`에 헤더/푸터까지 직접 구현하거나, `header` prop이 있는데도 직접 구현하는 경우가 있다.
+
+### 주요 Named Slot 패턴
+
+**Modal (BasicModal)**
+
+```tsx
+// ✅ header slot: 기본 헤더(title, backButton, closeButton) 대체
+// ✅ footer slot: 기본 푸터(confirmText, cancelText 버튼) 대체
+// ✅ footerExtra slot: 푸터 버튼 좌측 영역에 추가 콘텐츠 삽입
+<Modal
+  opened={isOpen}
+  onCancel={handleClose}
+  header={<CustomHeader />} // 기본 헤더 미표시
+  footer={<CustomFooter />} // 기본 푸터 미표시
+  footerExtra={<TextButton>도움말</TextButton>} // 푸터 좌측
+>
+  내용
+</Modal>
+```
+
+**BottomSheet**
+
+```tsx
+// ✅ title slot: 상단 제목 텍스트
+// ✅ subTitle slot: 제목 아래 부제목 텍스트
+// ✅ children: 내부 콘텐츠 (ReactNode 또는 render prop)
+<BottomSheet opened={isOpen} title='시트 제목' subTitle='부제목'>
+  {({ close }) => <Button onClick={close}>닫기</Button>}
+</BottomSheet>
+```
+
+**Input**
+
+```tsx
+// ✅ startAddon slot: 입력 필드 좌측 고정 요소
+// ✅ endAddon slot: 입력 필드 우측 고정 요소
+<Input startAddon={<span>￦</span>} endAddon={<span>.00</span>} placeholder='금액 입력' />
+```
+
+**FormField**
+
+```tsx
+// ✅ label: 라벨 텍스트 (string 또는 ReactNode)
+// ✅ rightAddon: 라벨 우측 추가 요소
+// ✅ formHelperText: 입력 하단 도움말 텍스트
+<FormField
+  label='이름'
+  rightAddon={<TextButton kind='link'>선택 사항</TextButton>}
+  formHelperText='실명을 입력하세요'
+  status='error'
+>
+  <Input placeholder='이름 입력' />
+</FormField>
+```
+
+**Popover / FloatingModal**
+
+```tsx
+// ✅ Popover: content slot (팝오버 내부 콘텐츠)
+// children은 트리거 요소 (클릭 시 팝오버 열림)
+<Popover
+  content={<div>팝오버 내용</div>}
+  // 또는 render prop:
+  content={({ close }) => <Button onClick={close}>닫기</Button>}
+>
+  <Button>팝오버 열기</Button>
+</Popover>
+// ✅ FloatingModal: trigger slot (모달을 열고 닫는 트리거)
+<FloatingModal
+  trigger={<Button>모달 열기</Button>}
+  title="제목"
+>
+  내용
+</FloatingModal>
+```
+
+---
+
+## 클래스 #8 — Negative Guidance (흔한 잘못된 패턴)
+
+### 무엇이 문제인가
+
+특정 컴포넌트는 API 형태가 직관적이지 않아 흔히 잘못 사용된다. 이 클래스는 타입 레벨에서 막기 어려운 _의미론적 오용 패턴_을 차단한다.
+
+---
+
+### 8-A. DropdownComposite: top-level options 없음
+
+```tsx
+// ❌ DropdownComposite는 top-level options/value/onChange를 받지 않음
+<DropdownComposite
+  options={options}    // ← 이 prop 없음
+  value={value}        // ← 이 prop 없음
+  onChange={setValue}  // ← 이 prop 없음
+/>
+// ✅ dropdownProps와 inputProps로 분리해서 전달
+<DropdownComposite
+  dropdownProps={{
+    options: options,
+    value: selectedValue,
+  }}
+  inputProps={{
+    width: 300,
+    placeholder: '검색어 입력',
+  }}
+  onSubmit={({ dropdownValue }) => handleSubmit(dropdownValue)}
+  onReset={({ dropdownValue }) => handleReset(dropdownValue)}
+/>
+```
+
+`DropdownComposite`는 Dropdown + Input의 복합 컴포넌트다. Dropdown 관련 props는 `dropdownProps`에, Input 관련 props는 `inputProps`에 전달한다.
+
+---
+
+### 8-B. Tooltip/Popover children: Fragment 금지
+
+```tsx
+// ❌ Fragment를 children으로 전달하면 cloneElement ref 주입 실패
+<Tooltip content="설명">
+  <>
+    <Button>버튼</Button>
+  </>
+</Tooltip>
+// ❌ 여러 자식 요소 나열
+<Popover content={<div>내용</div>}>
+  <Button>버튼1</Button>
+  <Button>버튼2</Button>  // 두 번째 요소는 트리거가 되지 않음
+</Popover>
+// ✅ 단일 ReactElement
+<Tooltip content="설명">
+  <Button>버튼</Button>
+</Tooltip>
+<Popover content={<div>내용</div>}>
+  <Button>팝오버 열기</Button>
+</Popover>
+```
+
+`Tooltip`과 `Popover`는 `cloneElement`로 children에 `ref`와 이벤트 핸들러를 주입한다. children이 Fragment이거나 여러 요소면 주입이 실패한다.
+
+---
+
+### 8-C. Dropdown: value만 전달하면 read-only
+
+```tsx
+// ❌ value만 전달하면 선택이 유지되지 않음 (onChange 없으면 내부 state 없음)
+<Dropdown options={options} value={selectedValue} />
+// ✅ value + onChange는 항상 함께
+<Dropdown
+  options={options}
+  value={selectedValue}
+  onChange={(value) => setSelectedValue(value)}
+/>
+```
+
+`Dropdown`은 내부 선택 state가 없다. `value`+`onChange` 없이 사용하면 옵션이 선택되지 않는 것처럼 보인다.
+
+---
+
+### 8-D. Alert/Confirm: JSX 렌더링 vs 함수 호출
+
+```tsx
+// ❌ AlertModal/ConfirmModal JSX를 일반 모달처럼 열면 안 됨
+// (기술적으로는 가능하지만 일반적이지 않다)
+const [isOpen, setIsOpen] = useState(false);
+<AlertModal opened={isOpen} onClose={() => setIsOpen(false)} title='알림' />;
+// ✅ Alert()/Confirm() 명령형 함수 호출 권장
+import { Alert, Confirm } from '@croquiscom/pds';
+const handleDelete = async () => {
+  const confirmed = await Confirm({
+    title: '삭제하시겠어요?',
+    text: '이 작업은 되돌릴 수 없습니다.',
+    confirmText: '삭제',
+    cancelText: '취소',
+  });
+  if (confirmed) {
+    await deleteItem();
+  }
+};
+// Alert: await로 닫힘 후 흐름 제어 가능
+await Alert({
+  title: '오류',
+  text: '처리 중 오류가 발생했습니다.',
+});
+```
+
+> `Confirm()`: `Promise\<boolean\>` — 확인 클릭 시 `true`, 취소/ESC 시 `false`. `Alert()`: `Promise\<boolean | undefined\>` — 닫힘 시 `undefined`. `onConfirm`이 `Promise\<void\>`를 반환하면 resolve 전까지 확인 버튼이 자동 `disabled` 상태가 되므로 별도 loading state를 구현할 필요가 없다.
+
+---
+
+### 8-E. tabs onChange는 사실상 필수
+
+```tsx
+// ❌ activeTabId만 전달하고 onChange 생략 → 탭이 전환되지 않음
+<LineTabs activeTabId={activeTab}>
+  <LineTab id="tab1">탭 1</LineTab>
+  <LineTab id="tab2">탭 2</LineTab>
+</LineTabs>
+// ✅ activeTabId + onChange 항상 함께
+<LineTabs activeTabId={activeTab} onChange={setActiveTab}>
+  <LineTab id="tab1">탭 1</LineTab>
+  <LineTab id="tab2">탭 2</LineTab>
+</LineTabs>
+```
+
+`LineTabs`, `BoxTabs`, `PanelTabs`는 내부 탭 선택 state가 없다. `activeTabId`와 `onChange`는 타입상 optional이지만, 외부 제어 없이는 탭이 전환되지 않는다.

package/pds-skills/resources/index.txt

@@ -9,6 +9,8 @@
 - [Guide/Common Mistakes](resources/guides/guide-common-mistakes.md)
 - [Guide/Foundation Usage](resources/guides/guide-foundation-usage.md)
 - [Guide/Style Utilities](resources/guides/guide-style-utilities.md)
+- [Guide/Component Decision Tree](resources/guides/guide-component-decision-tree.md)
+- [Guide/Composition Patterns](resources/guides/guide-composition-patterns.md)
 - [Guide/Icon Unicode Lookup](resources/guides/guide-icon-unicode-lookup.md)
 - [Guide/Icon Mapping](resources/guides/guide-icon-mapping.md)
 - [Foundation/Colors](resources/components/foundation-colors.txt)