@j-solution/components 1.0.0

package/USAGE_GUIDE.md

@@ -0,0 +1,748 @@
+# J-Component 라이브러리 사용 가이드
+
+> Vue.js 3 기반 Atomic Design 패턴 컴포넌트 라이브러리 사용 가이드
+
+## 📋 목차
+
+1. [프로젝트 개요](#프로젝트-개요)
+2. [컴포넌트 목록](#컴포넌트-목록)
+3. [컴포넌트 배치 가이드](#컴포넌트-배치-가이드)
+4. [컴포넌트 활용 가이드](#컴포넌트-활용-가이드)
+5. [기본 사용 규칙](#기본-사용-규칙)
+6. [고급 사용법](#고급-사용법)
+   - [JDynamicTabs - 경로 기반 컴포넌트 로딩](#jdynamictabs---경로-기반-컴포넌트-로딩)
+7. [레이아웃 템플릿 가이드](#레이아웃-템플릿-가이드)
+
+---
+
+## 프로젝트 개요
+
+J-Component는 Vue.js 3와 TypeScript를 기반으로 한 재사용 가능한 UI 컴포넌트 라이브러리입니다.
+
+### 핵심 특징
+
+- **Atomic Design 패턴**: Atoms → Molecules → Organisms → Templates 계층 구조
+- **TypeScript 완전 지원**: 타입 안정성 보장
+- **shadcn/ui 기반**: 일관된 디자인 시스템
+- **TailwindCSS**: 유틸리티 기반 스타일링
+- **다크모드 지원**: 라이트/다크 모드 자동 전환
+- **CSS 자동 포함** (NPM 패키지): 컴포넌트만 import하면 스타일이 자동으로 적용됩니다
+
+### 기술 스택
+
+- Vue.js 3.5
+- TypeScript 5.9
+- TailwindCSS 3.4
+- shadcn/ui (radix-vue 기반)
+
+### 설치 및 사용
+
+#### NPM 패키지 사용 (권장)
+
+```ts
+import { JButton } from '@j-solution/components'
+// CSS는 자동으로 포함됨 - 별도 import 불필요
+```
+
+> 💡 **참고**: NPM 패키지는 패키지 진입점에서 CSS가 자동으로 import되므로, 컴포넌트만 import하면 스타일이 자동으로 적용됩니다.
+
+#### Standard 방식 사용 (파일 복사)
+
+```ts
+import { JButton } from '@/components'
+// themes.css를 별도로 import해야 함 (INSTALLATION_GUIDE.md 참고)
+```
+
+> 📖 **설치 가이드**: 자세한 설치 방법은 [INSTALLATION_GUIDE.md](./INSTALLATION_GUIDE.md)를 참고하세요.
+
+---
+
+## 컴포넌트 목록
+
+### Atoms (원자) - 22개
+
+기본적인 UI 요소들로, 더 이상 분해할 수 없는 최소 단위의 컴포넌트입니다.
+
+| 컴포넌트 | 설명 | 주요 용도 |
+|---------|------|----------|
+| **JAvatar** | 사용자 아바타 | 프로필 이미지 표시 |
+| **JBadge** | 상태 표시 배지 | 상태, 카테고리 표시 |
+| **JButton** | 버튼 | 액션 실행, 폼 제출 |
+| **JCheckbox** | 체크박스 | 다중 선택 |
+| **JCombo** | 드롭다운 선택 | 단일/다중 선택 |
+| **JDatepicker** | 날짜 선택기 | 날짜 입력 |
+| **JDivider** | 구분선 | 콘텐츠 구분 |
+| **JGrid** | 데이터 그리드 | 테이블 데이터 표시 (AG Grid 기반) |
+| **JIcon** | 아이콘 | 시각적 표시 |
+| **JImage** | 이미지 | 이미지 표시 |
+| **JInput** | 텍스트 입력 필드 | 단일 라인 텍스트 입력 |
+| **JKbd** | 키보드 단축키 표시 | 단축키 안내 |
+| **JLabel** | 라벨 | 폼 필드 라벨 |
+| **JLink** | 링크 | 네비게이션 |
+| **JPopover** | 팝오버 | 추가 정보 표시 |
+| **JProgress** | 진행률 표시 | 작업 진행 상태 |
+| **JRadio** | 라디오 버튼 | 단일 선택 |
+| **JSearchCombo** | 검색 가능한 드롭다운 | 많은 옵션 중 검색 선택 |
+| **JSpinner** | 로딩 스피너 | 로딩 상태 표시 |
+| **JSwitch** | 토글 스위치 | ON/OFF 설정 |
+| **JTextarea** | 멀티라인 텍스트 입력 | 여러 라인 텍스트 입력 |
+| **JTooltip** | 툴팁 | 추가 설명 표시 |
+
+### Molecules (분자) - 11개
+
+여러 Atoms를 조합하여 만든 더 복잡한 컴포넌트입니다.
+
+| 컴포넌트 | 설명 | 주요 용도 |
+|---------|------|----------|
+| **JAccordion** | 접을 수 있는 콘텐츠 섹션 | FAQ, 상세 정보 접기/펼치기 |
+| **JAlert** | 알림 메시지 표시 | 성공/경고/에러 메시지 |
+| **JBreadcrumb** | 페이지 네비게이션 경로 | 현재 위치 표시 |
+| **JButtonGroup** | 버튼 그룹 | 관련 버튼 묶기 |
+| **JCard** | 카드 컴포넌트 | 콘텐츠 그룹화 |
+| **JContextMenu** | 우클릭 컨텍스트 메뉴 | 우클릭 메뉴 |
+| **JFormField** | 폼 필드 래퍼 | 라벨, 에러 메시지 포함 폼 필드 |
+| **JGroupCombo** | 그룹화된 드롭다운 | 카테고리별 선택 |
+| **JSearchAddr** | 주소 검색 | Daum Postcode API 활용 |
+| **JTabs** | 탭 UI | 콘텐츠 탭 전환 |
+| **JTitlebar** | 타이틀바 | 페이지/섹션 제목 및 액션 |
+
+### Organisms (유기체) - 9개
+
+Molecules와 Atoms를 조합하여 만든 완전한 기능을 가진 컴포넌트입니다.
+
+| 컴포넌트 | 설명 | 주요 용도 |
+|---------|------|----------|
+| **JDynamicForm** | 스키마 기반 동적 폼 | JSON 스키마로 폼 자동 생성 |
+| **JDynamicTabs** | 동적 탭 관리 | 런타임에 탭 추가/제거 |
+| **JFormModal** | 폼 모달 | JDynamicForm 기반 모달 폼 |
+| **JHeader** | 애플리케이션 헤더 | 상단 헤더 영역 |
+| **JModal** | 모달 다이얼로그 | 다이얼로그 표시 |
+| **JPageContainer** | 페이지 컨테이너 | 페이지 기본 레이아웃 |
+| **JSearchPanel** | 검색 조건 패널 | JDynamicForm 기반 검색 UI |
+| **JSidebarAdvanced** | 고급 사이드바 | 검색, 즐겨찾기, 다단계 메뉴 |
+| **JSidebarSimple** | 간단한 사이드바 | 다단계 메뉴, 검색 |
+
+### Templates (템플릿) - 3개
+
+Organisms를 조합하여 만든 페이지 레이아웃 구조입니다.
+
+| 컴포넌트 | 설명 | 주요 용도 |
+|---------|------|----------|
+| **JLayout** | 기본 레이아웃 | 커스텀 레이아웃 구성 |
+| **JLayoutAdvanced** | 고급 레이아웃 | JHeader + JSidebarAdvanced + JDynamicTabs |
+| **JLayoutSimple** | 간단한 레이아웃 | JHeader + JSidebarSimple + JPageContainer |
+
+---
+
+## 컴포넌트 배치 가이드
+
+### Atomic Design 계층 구조
+
+컴포넌트는 다음 계층 구조를 따릅니다:
+
+```
+Templates (템플릿)
+    └── Organisms (유기체)
+            └── Molecules (분자)
+                    └── Atoms (원자)
+```
+
+### 배치 원칙
+
+1. **하위 계층 우선 사용**
+   - 상위 계층에 해당 컴포넌트가 없을 때에 한해서, 가능한 한 가장 낮은 계층의 컴포넌트를 사용하세요
+   - 예: 단순 버튼은 `JButton` (Atoms) 사용, `JButtonGroup` (Molecules)은 여러 버튼을 묶을 때만 사용
+
+2. **조합 우선**
+   - 기존 컴포넌트로 원하는 기능을 구현할 수 있는 경우, 새로운 컴포넌트를 만들기보다 기존 컴포넌트를 조합하여 사용하세요
+   - 예: `JCard` + `JButton` + `JInput` 조합으로 카드 형태의 폼 구성
+
+3. **템플릿 활용**
+   - 전체 페이지 레이아웃은 Templates 사용
+   - 예: `JLayoutAdvanced` 또는 `JLayoutSimple` 사용
+
+### 계층별 사용 가이드
+
+#### Atoms 사용 시
+
+```vue
+<template>
+  <!-- 단일 기능만 필요한 경우 -->
+  <JButton @click="handleClick">저장</JButton>
+  <JInput v-model="name" placeholder="이름 입력" />
+</template>
+```
+
+#### Molecules 사용 시
+
+```vue
+<template>
+  <!-- 여러 Atoms 조합이 필요한 경우 -->
+  <JFormField 
+    type="input"
+    label="이름" 
+    required
+    v-model="name"
+    placeholder="이름을 입력하세요"
+  />
+  
+  <JCard title="제목">
+    <p>콘텐츠</p>
+  </JCard>
+</template>
+```
+
+#### Organisms 사용 시
+
+```vue
+<template>
+  <!-- 완전한 기능 블록이 필요한 경우 -->
+  <JModal :open="isOpen" title="확인" @confirm="handleConfirm" />
+  
+  <JDynamicForm :schema="formSchema" v-model="formData" />
+</template>
+```
+
+#### Templates 사용 시
+
+```vue
+<template>
+  <!-- 전체 페이지 레이아웃 -->
+  <JLayoutAdvanced 
+    :menu-items="menuItems"
+    :favorites="favorites"
+  >
+    <template #content-tab-{id}>
+      <RouterView />
+    </template>
+  </JLayoutAdvanced>
+</template>
+```
+
+---
+
+## 컴포넌트 활용 가이드
+
+### 상황별 추천 컴포넌트
+
+#### 폼 입력
+
+| 상황 | 추천 컴포넌트 | 이유 |
+|------|--------------|------|
+| 단일 라인 텍스트 입력 | `JInput` | 가장 기본적인 텍스트 입력 |
+| 여러 라인 텍스트 입력 | `JTextarea` | 긴 텍스트 입력 |
+| 날짜 선택 | `JDatepicker` | 날짜 선택 UI 제공 |
+| 단일 선택 (옵션 적음) | `JCombo` | 드롭다운 선택 |
+| 단일 선택 (옵션 많음) | `JSearchCombo` | 검색 기능으로 옵션 탐색 용이 |
+| 다중 선택 | `JCombo` (multiple) | 다중 선택 지원 |
+| ON/OFF 설정 | `JSwitch` | 토글 스위치 UI |
+| 체크박스 선택 | `JCheckbox` | 다중 선택 |
+| 라디오 선택 | `JRadio` | 단일 선택 (옵션 표시) |
+| 폼 필드 (라벨 + 에러 포함) | `JFormField` | 라벨, 에러 메시지 자동 처리 |
+| 동적 폼 생성 | `JDynamicForm` | JSON 스키마로 폼 자동 생성 |
+
+#### 데이터 표시
+
+| 상황 | 추천 컴포넌트 | 이유 |
+|------|--------------|------|
+| 테이블 데이터 | `JGrid` | 정렬, 필터링, 페이지네이션 지원 |
+| 상태 표시 | `JBadge` | 색상으로 상태 구분 |
+| 진행률 표시 | `JProgress` | 작업 진행 상태 시각화 |
+| 로딩 표시 | `JSpinner` | 비동기 작업 로딩 표시 |
+
+#### 사용자 인터랙션
+
+| 상황 | 추천 컴포넌트 | 이유 |
+|------|--------------|------|
+| 액션 버튼 | `JButton` | 다양한 스타일 지원 |
+| 버튼 그룹 | `JButtonGroup` | 관련 버튼 묶기 |
+| 모달 다이얼로그 | `JModal` | 다양한 크기 지원 (sm, md, lg, xl, 2xl, full) |
+| 폼 모달 | `JFormModal` | JDynamicForm 기반 모달 |
+| 탭 전환 | `JTabs` | 정적 탭 |
+| 동적 탭 | `JDynamicTabs` | 런타임에 탭 추가/제거 |
+
+#### 레이아웃
+
+| 상황 | 추천 컴포넌트 | 이유 |
+|------|--------------|------|
+| 콘텐츠 그룹화 | `JCard` | 카드 형태로 콘텐츠 구분 |
+| 접기/펼치기 | `JAccordion` | 섹션 접기/펼치기 |
+| 페이지 헤더 | `JHeader` | 애플리케이션 상단 헤더 |
+| 사이드바 (고급) | `JSidebarAdvanced` | 검색, 즐겨찾기 지원 |
+| 사이드바 (간단) | `JSidebarSimple` | 기본 메뉴만 필요할 때 |
+| 전체 레이아웃 (고급) | `JLayoutAdvanced` | 탭 기반 멀티 페이지 |
+| 전체 레이아웃 (간단) | `JLayoutSimple` | 단일 페이지 레이아웃 |
+
+#### 피드백
+
+| 상황 | 추천 컴포넌트 | 이유 |
+|------|--------------|------|
+| 성공/경고/에러 메시지 | `JAlert` | 타입별 스타일 자동 적용 |
+| 추가 설명 | `JTooltip` | 호버 시 설명 표시 |
+| 추가 정보 | `JPopover` | 클릭 시 정보 표시 |
+
+#### 검색
+
+| 상황 | 추천 컴포넌트 | 이유 |
+|------|--------------|------|
+| 검색 조건 패널 | `JSearchPanel` | JDynamicForm 기반, 접기/펼치기 지원 |
+| 주소 검색 | `JSearchAddr` | Daum Postcode API 통합 |
+
+---
+
+## 기본 사용 규칙
+
+### Props 공통 규칙
+
+대부분의 입력 컴포넌트는 다음 공통 props를 지원합니다:
+
+| Prop | 타입 | 설명 | 기본값 |
+|------|------|------|--------|
+| `modelValue` | `string \| number \| boolean \| object` | `v-model` 양방향 데이터 바인딩 | - |
+| `placeholder` | `string` | 입력 전 표시되는 안내문 | `''` |
+| `disabled` | `boolean` | 비활성화 상태 | `false` |
+| `readonly` | `boolean` | 읽기 전용 상태 (Input/Textarea) | `false` |
+| `required` | `boolean` | 필수 입력/선택 여부 | `false` |
+| `id` | `string` | HTML id 속성 (label for 연결용) | - |
+| `name` | `string` | form 데이터 전송 시 키 이름 | - |
+| `styletype` | `string` | 스타일 테마 프리셋 | `'default'` |
+| `class` | `string` | 추가 CSS 클래스 | - |
+
+### styletype 사용 가이드
+
+`styletype` prop은 컴포넌트의 스타일을 빠르게 변경할 수 있는 프리셋입니다.
+
+#### JButton styletype
+
+```vue
+<JButton styletype="primary">Primary</JButton>
+<JButton styletype="secondary">Secondary</JButton>
+<JButton styletype="danger">Danger</JButton>
+<JButton styletype="outline">Outline</JButton>
+<JButton styletype="ghost">Ghost</JButton>
+<JButton styletype="link">Link</JButton>
+<JButton styletype="sm">Small</JButton>
+<JButton styletype="lg">Large</JButton>
+```
+
+**권장 사용:**
+- `primary`: 주요 액션 (저장, 확인 등)
+- `secondary`: 보조 액션
+- `danger`: 위험한 액션 (삭제 등)
+- `outline`: 덜 강조된 액션
+- `ghost`: 최소한의 시각적 강조
+
+### v-model 사용
+
+모든 입력 컴포넌트는 `v-model`을 지원합니다:
+
+```vue
+<template>
+  <JInput v-model="name" placeholder="이름" />
+  <JCombo v-model="selected" :options="options" />
+  <JSwitch v-model="enabled" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const name = ref('')
+const selected = ref(null)
+const enabled = ref(false)
+</script>
+```
+
+### JFormField 사용 권장사항
+
+폼 필드를 만들 때는 `JFormField`를 사용하세요. `label`, `error-msg` prop으로 값을 입력하면 UI 배치시 라벨과 에러 메시지가 포함됩니다. `type` prop으로 원하는 입력 컴포넌트를 선택할 수 있습니다:
+
+```vue
+<template>
+  <!-- type prop으로 입력 컴포넌트 선택 -->
+  <JFormField 
+    type="input"
+    label="이름" 
+    required 
+    error-msg="이름을 입력해주세요"
+    v-model="name"
+    placeholder="이름을 입력하세요"
+  />
+  
+  <JFormField 
+    type="combo"
+    label="카테고리"
+    v-model="category"
+    :options="categoryOptions"
+  />
+  
+  <JFormField 
+    type="datepicker"
+    label="생년월일"
+    v-model="birthDate"
+  />
+</template>
+```
+
+**장점:**
+- `type` prop으로 다양한 입력 컴포넌트 선택 가능 (input, textarea, combo, datepicker 등)
+- `label` prop으로 라벨 값을 입력하면 UI 배치시 라벨이 포함되며, 입력 필드와 자동 연결 (접근성)
+- `error-msg` prop으로 에러 메시지 값을 입력하면 UI 배치시 에러 메시지가 포함됨
+- 레이아웃 일관성 유지
+
+### JDynamicForm 사용 권장사항
+
+JSON 스키마로 폼을 자동 생성할 수 있습니다:
+
+```vue
+<template>
+  <JDynamicForm 
+    :schema="formSchema" 
+    v-model="formData"
+    @submit="handleSubmit"
+  />
+</template>
+
+<script setup>
+const formSchema = {
+  type: 'simple',  // 'simple' | 'sectioned' | 'wizard'
+  fields: [
+    {
+      controlName: 'name',
+      label: '이름',
+      type: 'input',
+      isRequired: true
+    },
+    {
+      controlName: 'email',
+      label: '이메일',
+      type: 'input',
+      inputType: 'email'
+    }
+  ]
+}
+</script>
+```
+
+**권장 사용:**
+- `simple`: 단순한 폼
+- `sectioned`: 섹션별로 구분된 폼
+- `wizard`: 단계별 입력 폼
+
+### 이벤트 처리
+
+컴포넌트는 표준 Vue 이벤트를 발생시킵니다. `v-model`과 함께 이벤트 핸들러를 사용할 수 있습니다:
+
+```vue
+<template>
+  <JButton @click="handleClick">클릭</JButton>
+  <JInput v-model="name" @change="handleChange" />
+  <JModal 
+    :open="isOpen" 
+    @confirm="handleConfirm" 
+    @cancel="handleCancel" 
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const name = ref('')
+const isOpen = ref(false)
+
+const handleClick = () => {
+  console.log('버튼 클릭')
+}
+
+const handleChange = (value) => {
+  console.log('값 변경:', value)
+}
+
+const handleConfirm = () => {
+  console.log('확인')
+  isOpen.value = false
+}
+
+const handleCancel = () => {
+  console.log('취소')
+  isOpen.value = false
+}
+</script>
+```
+
+---
+
+## 고급 사용법
+
+### JDynamicTabs - 경로 기반 컴포넌트 로딩
+
+`JDynamicTabs`는 런타임에 탭을 동적으로 추가/제거할 수 있는 컴포넌트입니다. 경로(`/user/info` 같은)만 가지고 있을 때 해당 경로의 Vue 컴포넌트를 탭 콘텐츠로 표시하는 방법에 대한 가이드입니다.
+
+#### 핵심 원칙
+
+**Route 통일성을 최우선으로 고려해야 합니다.**
+
+- ✅ Router가 있는 프로젝트: Router의 routes를 재사용하여 통일성 보장
+- ✅ Router가 없는 프로젝트: 독립적인 컴포넌트 로딩 방식 사용
+
+#### 방법 1: RouterView 사용 (Router가 있는 경우) ⭐ 권장
+
+#### 언제 사용
+- 프로젝트에 Vue Router가 설치되어 있는 경우
+- Router의 routes에 경로-컴포넌트 매핑이 이미 정의되어 있는 경우
+- Route 통일성을 보장해야 하는 경우
+
+#### 장점
+- ✅ **Route 통일성 보장**: Router의 routes를 재사용하므로 경로-컴포넌트 매핑 중복 없음
+- ✅ URL 동기화 자동: 브라우저 뒤로가기 지원
+- ✅ 라우트 가드 활용: Router의 네비게이션 가드 사용 가능
+- ✅ 코드 스플리팅 자동: Router의 lazy loading 활용
+- ✅ 유지보수 용이: Router 설정만 수정하면 됨
+
+#### 단점
+- Router 의존적: Vue Router 필수
+- RouterView는 Router의 현재 경로를 사용하므로, 각 탭에 독립적인 경로를 보장하려면 Router 관리 필요
+
+#### 사용 예제
+
+```vue
+<template>
+  <JDynamicTabs ref="tabsRef" :initial-tabs="initialTabs">
+    <!-- 경로 기반 동적 슬롯 - RouterView 사용 -->
+    <template
+      v-for="tab in allTabs"
+      :key="tab.id"
+      #[`content-${tab.id}`]
+    >
+      <!-- RouterView: Router의 routes를 재사용하여 통일성 보장 -->
+      <RouterView 
+        v-if="tab.meta?.path"
+        :key="tab.id"
+      />
+    </template>
+  </JDynamicTabs>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { RouterView, useRouter } from 'vue-router'
+import JDynamicTabs from '@/components/organisms/JDynamicTabs.vue'
+import type { DynamicTab } from '@/types/dynamic-tabs.types'
+
+const router = useRouter()
+const tabsRef = ref()
+const allTabs = ref<DynamicTab[]>([])
+
+// 메뉴 클릭 시 탭 추가
+const handleMenuClick = (item) => {
+  const tabId = item.id || `tab-${item.path.replace(/[^a-zA-Z0-9]/g, '-')}`
+  
+  // addTab으로 탭 추가
+  tabsRef.value?.addTab({
+    id: tabId,
+    label: item.label,
+    closable: true,
+    meta: { path: item.path }, // 경로를 meta에 저장
+  })
+  
+  // allTabs에도 추가 (슬롯 이름 생성용)
+  allTabs.value.push({
+    id: tabId,
+    label: item.label,
+    meta: { path: item.path },
+  })
+  
+  // ⭐ Router의 경로로 이동 (Router에 이미 정의된 경로 사용)
+  router.push({ path: item.path })
+}
+</script>
+```
+
+#### 방법 2: 경로 기반 동적 import (Router가 없는 경우)
+
+#### 언제 사용
+- 프로젝트에 Vue Router가 설치되어 있지 않은 경우
+- Router의 routes와 완전히 독립적인 경로가 필요한 경우
+- Router 없이도 동작해야 하는 경우
+
+#### 장점
+- ✅ Router 독립적: Vue Router 없이도 사용 가능
+- ✅ 가벼움: 불필요한 라우팅 로직 없음
+- ✅ 코드 스플리팅 자동: 동적 import로 성능 최적화
+- ✅ 세밀한 제어: 탭별 독립적인 컴포넌트 관리
+
+#### 단점
+- ❌ Router의 routes와 중복 정의 필요
+- ❌ Route 통일성 보장 어려움
+- ❌ 경로 변경 시 두 곳 모두 수정 필요 (Router가 나중에 추가되는 경우)
+
+#### 사용 예제
+
+```vue
+<template>
+  <JDynamicTabs ref="tabsRef" :initial-tabs="initialTabs">
+    <template
+      v-for="tab in allTabs"
+      :key="tab.id"
+      #[`content-${tab.id}`]
+    >
+      <component 
+        v-if="tab.meta?.path"
+        :is="loadComponentByPath(tab.meta.path)" 
+        :key="tab.id"
+      />
+    </template>
+  </JDynamicTabs>
+</template>
+
+<script setup>
+import { ref, defineAsyncComponent, h } from 'vue'
+import JDynamicTabs from '@/components/organisms/JDynamicTabs.vue'
+import type { DynamicTab } from '@/types/dynamic-tabs.types'
+
+const tabsRef = ref()
+const allTabs = ref<DynamicTab[]>([])
+
+// 경로 기반 컴포넌트 로드
+const loadComponentByPath = (path: string) => {
+  // 경로를 컴포넌트 경로로 변환하는 매핑
+  // ⚠️ 주의: Router가 있다면 이 매핑은 Router의 routes와 중복될 수 있음
+  const componentMap: Record<string, () => Promise<any>> = {
+    '/user/info': () => import('@/pages/UserInfo.vue'),
+    '/user/list': () => import('@/pages/UserList.vue'),
+    '/product/detail': () => import('@/pages/ProductDetail.vue'),
+  }
+  
+  if (componentMap[path]) {
+    return defineAsyncComponent({
+      loader: componentMap[path],
+      loadingComponent: {
+        setup: () => () => h('div', { class: 'p-6' }, '로딩 중...'),
+      },
+      errorComponent: {
+        setup: () => () => h('div', { class: 'p-6 text-red-600' }, '컴포넌트 로드 실패'),
+      },
+      delay: 200,
+      timeout: 3000,
+    })
+  }
+  
+  // 매핑되지 않은 경로는 기본 컴포넌트 표시
+  return {
+    setup: () => () => h('div', { class: 'p-6' }, [
+      h('h2', { class: 'text-xl font-bold mb-4' }, '경로: ' + path),
+      h('p', { class: 'text-muted-foreground' }, '해당 경로의 컴포넌트를 매핑에 추가하세요.'),
+    ])
+  }
+}
+
+// 메뉴 클릭 시 탭 추가
+const handleMenuClick = (item) => {
+  const tabId = item.id || `tab-${item.path.replace(/[^a-zA-Z0-9]/g, '-')}`
+  
+  tabsRef.value?.addTab({
+    id: tabId,
+    label: item.label,
+    closable: true,
+    meta: { path: item.path },
+  })
+  
+  allTabs.value.push({
+    id: tabId,
+    label: item.label,
+    meta: { path: item.path },
+  })
+}
+</script>
+```
+
+#### 선택 가이드 (Decision Tree)
+
+```
+프로젝트에 Vue Router가 있나요?
+│
+├─ 예 → 방법 1 (RouterView 또는 Router의 routes 재사용)
+│       ✅ Route 통일성 보장
+│       ✅ 중복 정의 없음
+│       ✅ 유지보수 용이
+│
+└─ 아니오 → 방법 2 (동적 import)
+            ✅ Router 독립적
+            ✅ 가벼움
+            ⚠️ 나중에 Router 추가 시 중복 주의
+```
+
+#### 주의사항
+
+##### ⚠️ 방법 2를 사용 중인 프로젝트에서 Router 추가 시
+
+프로젝트에 나중에 Vue Router를 추가하는 경우:
+
+1. **즉시 방법 1로 마이그레이션 권장**
+   - Router의 routes를 재사용하여 통일성 보장
+   - 중복 정의 제거
+
+2. **마이그레이션이 어려운 경우**
+   - Router의 routes와 `componentMap`을 동기화 유지
+   - 경로 변경 시 두 곳 모두 수정
+
+##### ⚠️ 방법 1 사용 시 주의사항
+
+- RouterView는 Router의 현재 경로를 사용하므로, 각 탭에 독립적인 경로를 보장하려면 Router 관리 필요
+- 탭 내부에서 라우터 이동 시 전체 앱의 경로가 변경됨 (이를 방지하려면 추가 로직 필요)
+
+#### 요약
+
+| 항목 | 방법 1 (RouterView) | 방법 2 (동적 import) |
+|------|---------------------|---------------------|
+| **Router 필요** | 필수 | 불필요 |
+| **Route 통일성** | ✅ 보장 (Router routes 재사용) | ❌ 보장 어려움 (중복 정의 필요) |
+| **중복 코드** | 없음 | 경로-컴포넌트 매핑 중복 |
+| **유지보수** | Router만 수정 | 두 곳 모두 수정 필요 |
+| **권장 상황** | Router가 있는 경우 ⭐ | Router가 없는 경우 |
+
+---
+
+## 레이아웃 템플릿 가이드
+
+템플릿 컴포넌트는 전체 페이지 레이아웃을 구성하는 데 사용됩니다. 프로젝트의 요구사항에 따라 적절한 템플릿을 선택하세요.
+
+### JLayoutAdvanced 사용 시
+
+- 탭 기반 멀티 페이지 애플리케이션
+- 메뉴 클릭 시 자동 탭 생성
+- 검색, 즐겨찾기 기능 필요
+- 권한 관리 필요
+
+```vue
+<JLayoutAdvanced 
+  :menu-items="menuItems"
+  :favorites="favorites"
+  :permissions="permissions"
+>
+  <template #content-tab-{id}>
+    <RouterView />
+  </template>
+</JLayoutAdvanced>
+```
+
+### JLayoutSimple 사용 시
+
+- 단일 페이지 애플리케이션
+- 간단한 메뉴 구조
+- 검색 기능만 필요
+
+```vue
+<JLayoutSimple :menu-items="menuItems">
+  <template #content>
+    <YourPageContent />
+  </template>
+</JLayoutSimple>
+```
+
+> 💡 **레이아웃 컴포넌트 상세 정보**: [LAYOUT_TEMPLATE_GUIDE.md](./LAYOUT_TEMPLATE_GUIDE.md)를 참고하세요.
+
+---
+
+**문서 버전**: v1.0.0  
+**최종 업데이트**: 2025년 12월
+