@j-solution/components 1.2.1 → 1.4.0

package/USAGE_GUIDE.md

@@ -1,1755 +1,1047 @@
-# J-Component 라이브러리 사용 가이드
+# J-Component 사용 가이드
 
-> Vue.js 3 기반 Atomic Design 패턴 컴포넌트 라이브러리 사용 가이드
+> Claude Code를 이용한 프론트엔드 개발 시 참조하는 Props 기반 컴포넌트 사용 가이드
 
-## 📋 목차
-
-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 패키지 사용 (권장)
+## 설치 및 Import
 
 ```ts
-import { JButton } from '@j-solution/components'
-// CSS는 자동으로 포함됨 - 별도 import 불필요
-```
+// NPM 패키지 (권장) - CSS 자동 포함
+import { JButton, JInput, JGrid } from '@j-solution/components'
 
-> 💡 **참고**: NPM 패키지는 패키지 진입점에서 CSS가 자동으로 import되므로, 컴포넌트만 import하면 스타일이 자동으로 적용됩니다.
-
-#### Standard 방식 사용 (파일 복사)
-
-```ts
-import { JButton } from '@/components'
-// themes.css를 별도로 import해야 함 (INSTALLATION_GUIDE.md 참고)
+// Standard 방식 (파일 복사)
+import { JButton, JInput, JGrid } from '@/components'
 ```
 
-> 📖 **설치 가이드**: 자세한 설치 방법은 [INSTALLATION_GUIDE.md](./INSTALLATION_GUIDE.md)를 참고하세요.
-
 ---
 
 ## 컴포넌트 목록
 
-### Atoms (원자) - 25개
-
-기본적인 UI 요소들로, 더 이상 분해할 수 없는 최소 단위의 컴포넌트입니다.
-
-| 컴포넌트 | 설명 | 주요 용도 |
-|---------|------|----------|
-| **JAvatar** | 사용자 아바타 | 프로필 이미지 표시 |
-| **JBadge** | 상태 표시 배지 | 상태, 카테고리 표시 |
-| **JButton** | 버튼 | 액션 실행, 폼 제출 |
-| **JCheckbox** | 체크박스 | 다중 선택 |
-| **JCombo** | 드롭다운 선택 | 단일/다중 선택 |
-| **JDatepicker** | 날짜 선택기 | 날짜 입력 |
-| **JDivider** | 구분선 | 콘텐츠 구분 |
-| **JEditor** | 마크다운 에디터 | 마크다운 문서 작성 |
-| **JGrid** | 데이터 그리드 | 테이블 데이터 표시 (AG Grid 기반) |
-| **JIcon** | 아이콘 | 시각적 표시 |
-| **JImage** | 이미지 | 이미지 표시 |
-| **JInput** | 텍스트 입력 필드 | 단일 라인 텍스트 입력 |
-| **JKbd** | 키보드 단축키 표시 | 단축키 안내 |
-| **JLabel** | 라벨 | 폼 필드 라벨 |
-| **JLink** | 링크 | 네비게이션 |
-| **JPopover** | 팝오버 | 추가 정보 표시 |
-| **JPreview** | 마크다운/HTML 뷰어 | 마크다운 또는 HTML 문서 표시 |
-| **JProgress** | 진행률 표시 | 작업 진행 상태 |
-| **JRadio** | 라디오 버튼 | 단일 선택 |
-| **JSearchCombo** | 검색 가능한 드롭다운 | 많은 옵션 중 검색 선택 |
-| **JSpinner** | 로딩 스피너 | 로딩 상태 표시 |
-| **JSwitch** | 토글 스위치 | ON/OFF 설정 |
-| **JTextarea** | 멀티라인 텍스트 입력 | 여러 라인 텍스트 입력 |
-| **JToaster** | Toast 알림 컨테이너 | 전역 알림 메시지 표시 |
-| **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 |
+### Atoms (26개)
+
+| 컴포넌트 | 설명 |
+|---------|------|
+| JAvatar | 사용자 아바타 |
+| JBadge | 상태 표시 배지 |
+| JButton | 버튼 |
+| JCheckbox | 체크박스 (Y/N 문자열) |
+| JCombo | 드롭다운 선택 |
+| JDatepicker | 날짜 선택기 |
+| JDivider | 구분선 |
+| JEditor | 마크다운 에디터 |
+| JGrid | 데이터 그리드 (AG Grid) |
+| JIcon | 아이콘 (Lucide) |
+| JImage | 이미지 |
+| JInput | 텍스트 입력 |
+| JKbd | 키보드 단축키 표시 |
+| JLabel | 라벨 |
+| JLink | 링크 |
+| JPopover | 팝오버 |
+| JPreview | 마크다운/HTML 뷰어 |
+| JProgress | 진행률 표시 |
+| JRadio | 라디오 버튼 (options 배열) |
+| JSearchCombo | 검색 가능한 드롭다운 |
+| JSpinner | 로딩 스피너 |
+| JSwitch | 토글 스위치 (Y/N 문자열) |
+| JTextarea | 멀티라인 텍스트 입력 |
+| JToaster | Toast 알림 컨테이너 |
+| JTooltip | 툴팁 |
+| JTree | 트리 뷰 |
+
+### Molecules (11개)
+
+| 컴포넌트 | 설명 |
+|---------|------|
+| JAccordion | 접기/펼치기 섹션 |
+| JAlert | 알림 메시지 |
+| JBreadcrumb | 경로 탐색 |
+| JButtonGroup | 버튼 그룹 |
+| JCard | 카드 |
+| JContextMenu | 우클릭 메뉴 |
+| JFormField | 폼 필드 래퍼 (label + error + 입력) |
+| JGroupCombo | 그룹화된 드롭다운 |
+| JSearchAddr | 주소 검색 (Daum API) |
+| JTabs | 탭 UI |
+| JTitlebar | 타이틀바 |
+
+### Organisms (9개)
+
+| 컴포넌트 | 설명 |
+|---------|------|
+| JDynamicForm | 스키마 기반 동적 폼 |
+| JDynamicTabs | 동적 탭 관리 |
+| JFormModal | 폼 모달 (JDynamicForm 기반) |
+| JHeader | 애플리케이션 헤더 |
+| JModal | 모달 다이얼로그 |
+| JPageContainer | 페이지 컨테이너 |
+| JSearchPanel | 검색 조건 패널 |
+| JSidebarAdvanced | 고급 사이드바 |
+| JSidebarSimple | 간단한 사이드바 |
+
+### Templates (3개)
+
+| 컴포넌트 | 설명 |
+|---------|------|
+| JLayout | 기본 레이아웃 (커스텀) |
+| JLayoutAdvanced | 고급 레이아웃 (탭 기반) |
+| JLayoutSimple | 간단한 레이아웃 (단일 페이지) |
 
 ---
 
-## 컴포넌트 배치 가이드
-
-### Atomic Design 계층 구조
-
-컴포넌트는 다음 계층 구조를 따릅니다:
-
-```
-Templates (템플릿)
-    └── Organisms (유기체)
-            └── Molecules (분자)
-                    └── Atoms (원자)
-```
-
-### 배치 원칙
-
-1. **하위 계층 우선 사용**
-   - 상위 계층에 해당 컴포넌트가 없을 때에 한해서, 가능한 한 가장 낮은 계층의 컴포넌트를 사용하세요
-   - 예: 단순 버튼은 `JButton` (Atoms) 사용, `JButtonGroup` (Molecules)은 여러 버튼을 묶을 때만 사용
-
-2. **조합 우선**
-   - 기존 컴포넌트로 원하는 기능을 구현할 수 있는 경우, 새로운 컴포넌트를 만들기보다 기존 컴포넌트를 조합하여 사용하세요
-   - 예: `JCard` + `JButton` + `JInput` 조합으로 카드 형태의 폼 구성
+## 공통 Props
 
-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` | 타입별 스타일 자동 적용 |
-| 전역 알림 메시지 (Toast) | `JToast` (함수) + `JToaster` (컴포넌트) | 화면 상단/하단에 일시적으로 표시되는 알림 |
-| 추가 설명 | `JTooltip` | 호버 시 설명 표시 |
-| 추가 정보 | `JPopover` | 클릭 시 정보 표시 |
-
-#### 검색
-
-| 상황 | 추천 컴포넌트 | 이유 |
-|------|--------------|------|
-| 검색 조건 패널 | `JSearchPanel` | JDynamicForm 기반, 접기/펼치기 지원 |
-| 주소 검색 | `JSearchAddr` | Daum Postcode API 통합 |
-
----
-
-## 기본 사용 규칙
-
-### Props 공통 규칙
-
-대부분의 입력 컴포넌트는 다음 공통 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'` |
+| `modelValue` | 컴포넌트별 상이 | v-model 바인딩 | - |
+| `placeholder` | `string` | 안내문 | `''` |
+| `disabled` | `boolean` | 비활성화 | `false` |
+| `readonly` | `boolean` | 읽기 전용 (Input/Textarea) | `false` |
+| `required` | `boolean` | 필수 여부 | `false` |
+| `id` | `string` | HTML id | - |
+| `name` | `string` | form 필드명 | - |
 | `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>
-```
+| 이벤트 | 설명 |
+|--------|------|
+| `update:modelValue` | v-model 업데이트 |
+| `change` | 값 변경 |
+| `focus` | 포커스 |
+| `blur` | 포커스 해제 |
 
-**권장 사용:**
-- `primary`: 주요 액션 (저장, 확인 등)
-- `secondary`: 보조 액션
-- `danger`: 위험한 액션 (삭제 등)
-- `outline`: 덜 강조된 액션
-- `ghost`: 최소한의 시각적 강조
+---
 
-### v-model 사용
+## Atoms Props 레퍼런스
 
-모든 입력 컴포넌트는 `v-model`을 지원합니다:
+### JButton
 
 ```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>
+<JButton
+  type="button"         <!-- 'button'|'submit'|'reset' -->
+  :disabled="false"
+  :loading="false"      <!-- true이면 스피너 표시 -->
+  @click="handler"
+>
+  저장
+</JButton>
 ```
 
-### 이벤트 처리
+---
 
-컴포넌트는 표준 Vue 이벤트를 발생시킵니다. `v-model`과 함께 이벤트 핸들러를 사용할 수 있습니다:
+### JInput
 
 ```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>
+<JInput
+  v-model="value"
+  type="text"           <!-- 'text'|'email'|'password'|'number'|'tel'|'url' -->
+  placeholder="입력하세요"
+  :disabled="false"
+  :readonly="false"
+  :required="false"
+  @change="handler"
+/>
 ```
 
-### 컴포넌트별 기본 사용법
-
-#### Atoms (원자 컴포넌트)
+---
 
-##### JAvatar - 사용자 아바타
+### JTextarea
 
 ```vue
-<template>
-  <!-- 기본 사용 -->
-  <JAvatar fallback="JD" />
-  
-  <!-- 이미지와 함께 사용 -->
-  <JAvatar 
-    src="https://example.com/avatar.jpg" 
-    alt="사용자 이름"
-    fallback="JD"
-    size="lg"
-    shape="circle"
-    status="online"
-  />
-</template>
-
-<script setup>
-import { JAvatar } from '@/components/atoms'
-</script>
+<JTextarea
+  v-model="value"
+  placeholder="입력하세요"
+  :rows="3"
+  :disabled="false"
+  :readonly="false"
+/>
 ```
 
-##### JBadge - 상태 표시 배지
-
-```vue
-<template>
-  <JBadge styletype="success">활성</JBadge>
-  <JBadge styletype="warning">대기</JBadge>
-  <JBadge styletype="danger">비활성</JBadge>
-  <JBadge styletype="primary" size="lg">프리미엄</JBadge>
-</template>
-
-<script setup>
-import { JBadge } from '@/components/atoms'
-</script>
-```
+---
 
-##### JCheckbox - 체크박스
+### JCombo
 
 ```vue
-<template>
-  <JCheckbox v-model="checked" label="동의합니다" />
-  <JCheckbox v-model="terms" label="약관에 동의합니다" required />
-</template>
-
-<script setup>
-import { ref } from 'vue'
-import { JCheckbox } from '@/components/atoms'
-
-const checked = ref(false)
-const terms = ref(false)
-</script>
+<JCombo
+  v-model="selected"
+  :options="[
+    { value: 'opt1', label: '옵션 1' },
+    { value: 'opt2', label: '옵션 2' },
+  ]"
+  placeholder="선택하세요"
+  :multiple="false"
+  :disabled="false"
+/>
 ```
 
-##### JCombo - 드롭다운 선택
-
-```vue
-<template>
-  <JCombo 
-    v-model="selected" 
-    :options="options"
-    placeholder="선택하세요"
-  />
-</template>
+---
 
-<script setup>
-import { ref } from 'vue'
-import { JCombo } from '@/components/atoms'
+### JSearchCombo
 
-const selected = ref('')
-const options = [
-  { value: 'option1', label: '옵션 1' },
-  { value: 'option2', label: '옵션 2' },
-  { value: 'option3', label: '옵션 3' },
-]
-</script>
-```
-
-##### JDatepicker - 날짜 선택기
+> **주의**: `modelValue`는 `{ value, label }` 객체 타입
 
 ```vue
-<template>
-  <JDatepicker 
-    v-model="date"
-    placeholder="날짜를 선택하세요"
-  />
-</template>
-
-<script setup>
-import { ref } from 'vue'
-import { JDatepicker } from '@/components/atoms'
-
-const date = ref(null)
-</script>
+<JSearchCombo
+  v-model="selectedOption"
+  :options="[
+    { value: '1', label: '항목 1' },
+    { value: '2', label: '항목 2' },
+  ]"
+  placeholder="선택해주세요."
+  searchPlaceholder="검색어 입력"
+  emptyText="검색 결과가 없습니다."
+  :multiple="false"
+  :disabled="false"
+/>
 ```
 
-##### JDivider - 구분선
-
-```vue
-<template>
-  <div>위쪽 콘텐츠</div>
-  <JDivider />
-  <div>아래쪽 콘텐츠</div>
-  
-  <!-- 텍스트와 함께 사용 -->
-  <JDivider>또는</JDivider>
-</template>
-
-<script setup>
-import { JDivider } from '@/components/atoms'
-</script>
+```ts
+const selectedOption = ref<{ value: string | number; label: string } | undefined>()
 ```
 
-##### JGrid - 데이터 그리드
-
-```vue
-<template>
-  <JGrid 
-    :column-defs="columnDefs"
-    :row-data="rowData"
-  />
-</template>
-
-<script setup>
-import { JGrid } from '@/components/atoms'
-
-const columnDefs = [
-  { field: 'name', headerName: '이름' },
-  { field: 'age', headerName: '나이' },
-  { field: 'email', headerName: '이메일' },
-]
+---
 
-const rowData = [
-  { name: '홍길동', age: 30, email: 'hong@example.com' },
-  { name: '김철수', age: 25, email: 'kim@example.com' },
-]
-</script>
-```
+### JCheckbox
 
-##### JIcon - 아이콘
+> **주의**: `modelValue`는 `boolean`이 아닌 `'Y'` / `'N'` 문자열
 
 ```vue
-<template>
-  <JIcon name="user" size="lg" />
-  <JIcon name="settings" styletype="primary" />
-  <JIcon name="check" styletype="success" />
-</template>
-
-<script setup>
-import { JIcon } from '@/components/atoms'
-</script>
+<JCheckbox
+  v-model="checked"
+  label="동의합니다"
+  :disabled="false"
+  :required="false"
+/>
 ```
 
-##### JImage - 이미지
-
-```vue
-<template>
-  <JImage 
-    src="https://example.com/image.jpg"
-    alt="이미지 설명"
-    width="300"
-    height="200"
-  />
-</template>
-
-<script setup>
-import { JImage } from '@/components/atoms'
-</script>
+```ts
+const checked = ref('N')  // 'Y' 또는 'N'
 ```
 
-##### JKbd - 키보드 단축키 표시
-
-```vue
-<template>
-  <div>
-    저장: <JKbd>Ctrl</JKbd> + <JKbd>S</JKbd>
-    복사: <JKbd>Ctrl</JKbd> + <JKbd>C</JKbd>
-  </div>
-</template>
+---
 
-<script setup>
-import { JKbd } from '@/components/atoms'
-</script>
-```
+### JSwitch
 
-##### JLabel - 라벨
+> **주의**: `modelValue`는 `boolean`이 아닌 `'Y'` / `'N'` 문자열
 
 ```vue
-<template>
-  <JLabel for="input-id">이름</JLabel>
-  <JInput id="input-id" v-model="name" />
-</template>
-
-<script setup>
-import { ref } from 'vue'
-import { JLabel, JInput } from '@/components/atoms'
-
-const name = ref('')
-</script>
+<JSwitch
+  v-model="enabled"
+  label="알림 받기"
+  :disabled="false"
+/>
 ```
 
-##### JLink - 링크
-
-```vue
-<template>
-  <JLink href="/about">소개</JLink>
-  <JLink href="/contact" styletype="primary">연락처</JLink>
-</template>
-
-<script setup>
-import { JLink } from '@/components/atoms'
-</script>
-```
-
-##### JPopover - 팝오버
-
-```vue
-<template>
-  <JPopover>
-    <template #trigger>
-      <JButton>팝오버 열기</JButton>
-    </template>
-    <template #content>
-      <div class="p-4">
-        <p>팝오버 내용입니다.</p>
-      </div>
-    </template>
-  </JPopover>
-</template>
-
-<script setup>
-import { JPopover, JButton } from '@/components/atoms'
-</script>
+```ts
+const enabled = ref('N')  // 'Y' 또는 'N'
 ```
 
-##### JProgress - 진행률 표시
-
-```vue
-<template>
-  <JProgress :value="progress" />
-  <JProgress :value="75" styletype="success" />
-</template>
-
-<script setup>
-import { ref } from 'vue'
-import { JProgress } from '@/components/atoms'
+---
 
-const progress = ref(50)
-</script>
-```
+### JRadio
 
-##### JRadio - 라디오 버튼
+> **주의**: `options` 배열로 라디오 항목 정의 (개별 나열 아님)
 
 ```vue
-<template>
-  <JRadio v-model="selected" value="option1" label="옵션 1" />
-  <JRadio v-model="selected" value="option2" label="옵션 2" />
-  <JRadio v-model="selected" value="option3" label="옵션 3" />
-</template>
-
-<script setup>
-import { ref } from 'vue'
-import { JRadio } from '@/components/atoms'
-
-const selected = ref('option1')
-</script>
+<JRadio
+  v-model="selected"
+  :options="[
+    { value: 'opt1', label: '옵션 1' },
+    { value: 'opt2', label: '옵션 2' },
+    { value: 'opt3', label: '옵션 3', disabled: true },
+  ]"
+/>
 ```
 
-##### JSearchCombo - 검색 가능한 드롭다운
-
-```vue
-<template>
-  <JSearchCombo 
-    v-model="selected"
-    :options="options"
-    placeholder="검색하여 선택하세요"
-  />
-</template>
-
-<script setup>
-import { ref } from 'vue'
-import { JSearchCombo } from '@/components/atoms'
-
-const selected = ref('')
-const options = [
-  { value: '1', label: '항목 1' },
-  { value: '2', label: '항목 2' },
-  // ... 많은 옵션들
-]
-</script>
-```
+---
 
-##### JSpinner - 로딩 스피너
+### JDatepicker
 
 ```vue
-<template>
-  <JSpinner v-if="loading" />
-  <div v-else>콘텐츠</div>
-</template>
-
-<script setup>
-import { ref } from 'vue'
-import { JSpinner } from '@/components/atoms'
-
-const loading = ref(true)
-</script>
+<JDatepicker
+  v-model="date"
+  placeholder="날짜를 선택하세요"
+  :disabled="false"
+/>
 ```
 
-##### JSwitch - 토글 스위치
-
-```vue
-<template>
-  <JSwitch v-model="enabled" label="알림 받기" />
-</template>
-
-<script setup>
-import { ref } from 'vue'
-import { JSwitch } from '@/components/atoms'
-
-const enabled = ref(false)
-</script>
+```ts
+const date = ref<string | null>(null)  // ISO 8601: 'YYYY-MM-DD'
 ```
 
-##### JTextarea - 멀티라인 텍스트 입력
-
-```vue
-<template>
-  <JTextarea 
-    v-model="description"
-    placeholder="설명을 입력하세요"
-    rows="5"
-  />
-</template>
-
-<script setup>
-import { ref } from 'vue'
-import { JTextarea } from '@/components/atoms'
-
-const description = ref('')
-</script>
-```
+---
 
-##### JTooltip - 툴팁
+### JGrid (AG Grid)
 
 ```vue
-<template>
-  <JTooltip content="이것은 툴팁입니다">
-    <JButton>호버하세요</JButton>
-  </JTooltip>
-</template>
-
-<script setup>
-import { JTooltip, JButton } from '@/components/atoms'
-</script>
+<JGrid
+  :column-defs="columnDefs"
+  :row-data="rowData"
+  theme="ag-theme-balham"
+  :pagination="false"
+  :checkbox="false"
+  :summary-column="false"
+  :hidden-column="false"
+  :enable-grouping="false"     <!-- Enterprise -->
+  :enable-pivot="false"        <!-- Enterprise -->
+  :enable-excel-export="false" <!-- Enterprise -->
+/>
 ```
 
-##### JButton - 버튼
-
-**주요 props**: `styletype` (primary, secondary, danger, outline, ghost, link, sm, lg), `disabled`, `loading`
-
-**권장 사용 시나리오**:
-- `styletype="primary"`: 주요 액션 (저장, 확인 등)
-- `styletype="secondary"`: 보조 액션
-- `styletype="danger"`: 위험한 액션 (삭제 등)
-- `styletype="outline"`: 덜 강조된 액션
-- `styletype="ghost"`: 최소한의 시각적 강조
-- `disabled`: 비활성화 상태
-- `loading`: 비동기 작업 진행 중 표시
-
-##### JInput - 텍스트 입력 필드
-
-**주요 props**: `modelValue`, `type` (text, email, password, number 등), `placeholder`, `disabled`, `readonly`, `required`, `styletype` (default, error, success, warning, sm, lg)
-
-**권장 사용 시나리오**:
-- `type="text"`: 일반 텍스트 입력
-- `type="email"`: 이메일 주소 입력
-- `type="password"`: 비밀번호 입력
-- `type="number"`: 숫자 입력
-- `styletype="error"`: 유효성 검사 실패 시
-- `styletype="success"`: 유효성 검사 통과 시
-- `readonly`: 읽기 전용 표시
-
-##### JEditor - 마크다운 에디터
-
-**주요 props**: `modelValue` (마크다운 문자열), `placeholder`, `disabled`, `readonly`, `height`, `theme` (light, dark)
-
-**권장 사용 시나리오**:
-- `modelValue`: v-model로 마크다운 내용 바인딩
-- `height`: 에디터 높이 설정 (기본값: 500)
-- `theme`: 다크모드 지원
-- `readonly`: 읽기 전용 모드 (프리뷰 전용)
-
-##### JPreview - 마크다운/HTML 뷰어
-
-**주요 props**: `modelValue` (마크다운 또는 HTML 문자열), `theme` (light, dark)
-
-**권장 사용 시나리오**:
-- `modelValue`: 마크다운 또는 HTML 문자열 자동 감지 및 렌더링
-- HTML 문서는 `<!DOCTYPE html>` 또는 `<html>` 태그로 시작하면 자동 감지
-- 마크다운은 그 외 모든 경우에 자동 처리
-- `theme`: 다크모드 지원
-- JEditor로 작성한 마크다운을 자동으로 변환하여 표시
-
-##### JToaster - Toast 알림 컨테이너
-
-**권장 사용 시나리오**:
-- 앱의 루트 레벨에 `<JToaster />` 컴포넌트 추가
-- `JToast` 함수와 함께 사용: `JToast.success()`, `JToast.error()`, `JToast.info()`, `JToast.warning()`
-- 자동 사라짐 기능 내장
-- 여러 Toast 동시 표시 가능
-
-#### Molecules (분자 컴포넌트)
-
-##### JAccordion - 접을 수 있는 콘텐츠 섹션
-
-```vue
-<template>
-  <JAccordion 
-    :items="items"
-    type="single"
-    collapsible
-  />
-</template>
-
-<script setup>
-import { JAccordion } from '@/components/molecules'
-
-const items = [
-  {
-    value: 'item-1',
-    title: '첫 번째 항목',
-    content: '첫 번째 항목의 내용입니다.',
-  },
-  {
-    value: 'item-2',
-    title: '두 번째 항목',
-    content: '두 번째 항목의 내용입니다.',
-  },
+```ts
+const columnDefs = [
+  { field: 'name', headerName: '이름' },
+  { field: 'age', headerName: '나이' },
+  { field: 'email', headerName: '이메일' },
 ]
-</script>
-```
-
-##### JAlert - 알림 메시지 표시
-
-```vue
-<template>
-  <JAlert 
-    variant="default"
-    title="알림"
-    description="이것은 알림 메시지입니다."
-    button-text="확인"
-    :show-footer="true"
-    @confirm="handleConfirm"
-  />
-</template>
 
-<script setup>
-import { JAlert } from '@/components/molecules'
+const rowData = [
+  { name: '홍길동', age: 30, email: 'hong@example.com' },
+]
 
-const handleConfirm = () => {
-  console.log('확인 클릭')
-}
-</script>
+// ref로 접근하여 Excel 내보내기
+gridRef.value?.exportToExcel()
 ```
 
-##### JBreadcrumb - 페이지 네비게이션 경로
-
-```vue
-<template>
-  <JBreadcrumb :items="breadcrumbItems" />
-</template>
-
-<script setup>
-import { JBreadcrumb } from '@/components/molecules'
-
-const breadcrumbItems = [
-  { label: '홈', href: '/' },
-  { label: '카테고리', href: '/category' },
-  { label: '현재 페이지' },
-]
-</script>
-```
+---
 
-##### JButtonGroup - 버튼 그룹
+### JIcon
 
 ```vue
-<template>
-  <JButtonGroup>
-    <JButton>저장</JButton>
-    <JButton>취소</JButton>
-    <JButton>삭제</JButton>
-  </JButtonGroup>
-</template>
-
-<script setup>
-import { JButtonGroup, JButton } from '@/components/molecules'
-</script>
+<JIcon
+  name="user"          <!-- Lucide 아이콘 이름 (필수) -->
+  size="md"            <!-- 'sm'|'md'|'lg'|'xl' -->
+  color="#333"          <!-- CSS 색상값 (선택) -->
+/>
 ```
 
-##### JCard - 카드 컴포넌트
-
-```vue
-<template>
-  <JCard 
-    title="카드 제목"
-    description="카드 설명"
-    footer="푸터 텍스트"
-  >
-    <p>카드 내용입니다.</p>
-  </JCard>
-</template>
-
-<script setup>
-import { JCard } from '@/components/molecules'
-</script>
-```
+---
 
-##### JContextMenu - 우클릭 컨텍스트 메뉴
+### JAvatar
 
 ```vue
-<template>
-  <JContextMenu>
-    <template #trigger>
-      <div>우클릭하세요</div>
-    </template>
-    <template #content>
-      <div class="p-2">
-        <div class="p-2 hover:bg-gray-100 cursor-pointer">복사</div>
-        <div class="p-2 hover:bg-gray-100 cursor-pointer">붙여넣기</div>
-        <div class="p-2 hover:bg-gray-100 cursor-pointer">삭제</div>
-      </div>
-    </template>
-  </JContextMenu>
-</template>
-
-<script setup>
-import { JContextMenu } from '@/components/molecules'
-</script>
+<JAvatar
+  src="https://example.com/avatar.jpg"
+  alt="사용자 이름"
+  fallback="JD"
+  size="lg"
+  shape="circle"
+  status="online"
+/>
 ```
 
-##### JGroupCombo - 그룹화된 드롭다운
-
-```vue
-<template>
-  <JGroupCombo 
-    v-model="selected"
-    :groups="groupedOptions"
-    placeholder="그룹에서 선택하세요"
-  />
-</template>
-
-<script setup>
-import { ref } from 'vue'
-import { JGroupCombo } from '@/components/molecules'
-
-const selected = ref('')
-const groupedOptions = [
-  {
-    label: '그룹 1',
-    options: [
-      { value: '1-1', label: '옵션 1-1' },
-      { value: '1-2', label: '옵션 1-2' },
-    ],
-  },
-  {
-    label: '그룹 2',
-    options: [
-      { value: '2-1', label: '옵션 2-1' },
-      { value: '2-2', label: '옵션 2-2' },
-    ],
-  },
-]
-</script>
-```
+---
 
-##### JSearchAddr - 주소 검색
+### JBadge
 
 ```vue
-<template>
-  <JSearchAddr 
-    v-model="address"
-    @select="handleAddressSelect"
-  />
-</template>
-
-<script setup>
-import { ref } from 'vue'
-import { JSearchAddr } from '@/components/molecules'
-
-const address = ref('')
-
-const handleAddressSelect = (data) => {
-  console.log('선택된 주소:', data)
-}
-</script>
+<JBadge size="md">활성</JBadge>
 ```
 
-##### JTabs - 탭 UI
-
-```vue
-<template>
-  <JTabs 
-    :tabs="tabs"
-    v-model:active-tab-id="activeTab"
-    @tab-change="handleTabChange"
-  />
-</template>
-
-<script setup>
-import { ref } from 'vue'
-import { JTabs } from '@/components/molecules'
-
-const activeTab = ref('tab1')
-const tabs = [
-  { id: 'tab1', label: '탭 1', closable: false },
-  { id: 'tab2', label: '탭 2', closable: true },
-  { id: 'tab3', label: '탭 3', closable: true },
-]
-
-const handleTabChange = (id) => {
-  console.log('탭 변경:', id)
-}
-</script>
-```
+---
 
-##### JTitlebar - 타이틀바
+### JProgress
 
 ```vue
-<template>
-  <JTitlebar 
-    title="페이지 제목"
-    description="페이지 설명"
-  >
-    <template #actions>
-      <JButton>액션 1</JButton>
-      <JButton>액션 2</JButton>
-    </template>
-  </JTitlebar>
-</template>
-
-<script setup>
-import { JTitlebar, JButton } from '@/components/molecules'
-</script>
+<JProgress :value="75" />
 ```
 
-##### JFormField - 폼 필드 래퍼
+---
+
+### JEditor
 
-**주요 props**: `type` (input, textarea, checkbox, switch, combo, radio, searchCombo, datepicker), `label`, `description`, `errorMsg`, `modelValue`, `placeholder`, `disabled`, `required`, `orientation` (vertical, horizontal, responsive), `labelAlign`, `labelWidth`
+```vue
+<JEditor
+  v-model="markdown"
+  placeholder="마크다운을 입력하세요..."
+  :height="500"
+  theme="light"        <!-- 'light'|'dark' -->
+  :disabled="false"
+  :readonly="false"
+  @save="handleSave"   <!-- Ctrl+S -->
+/>
+```
 
-**권장 사용 시나리오**:
-- `type` prop으로 원하는 입력 컴포넌트 선택
-- `label` prop으로 라벨 값을 입력하면 UI 배치시 라벨이 포함되며, 입력 필드와 자동 연결 (접근성)
-- `errorMsg` prop으로 에러 메시지 값을 입력하면 UI 배치시 에러 메시지가 포함됨
-- `orientation="horizontal"`: 레이블과 입력 필드를 가로로 배치
-- `orientation="vertical"`: 레이블과 입력 필드를 세로로 배치 (기본값)
-- `orientation="responsive"`: 화면 크기에 따라 자동 조정
-- 레이아웃 일관성 유지
+---
 
-#### Organisms (유기체 컴포넌트)
+### JPreview
 
-##### JDynamicForm - 스키마 기반 동적 폼
+```vue
+<JPreview
+  :model-value="markdownOrHtml"
+  theme="light"        <!-- 'light'|'dark' -->
+/>
+```
 
-**주요 props**: `schema` (JSON 스키마), `modelValue`, `type` (simple, sectioned, wizard)
+> HTML은 `<!DOCTYPE html>` 또는 `<html>` 태그로 시작하면 자동 감지, 그 외는 마크다운 처리
 
-**권장 사용 시나리오**:
-- `type="simple"`: 단순한 폼
-- `type="sectioned"`: 섹션별로 구분된 폼
-- `type="wizard"`: 단계별 입력 폼
-- JSON 스키마로 폼 자동 생성
-- `schema.fields` 배열에 필드 정의: `controlName`, `label`, `type`, `isRequired` 등
-- Props 기반의 사용을 권장합니다
+---
 
-##### JModal - 모달 다이얼로그
+### JTooltip
 
-**주요 props**: `open`, `size` (sm, md, lg, xl, 2xl, full), `title`, `description`, `show-footer`, `confirm-text`, `cancel-text`
+```vue
+<JTooltip
+  content="설명 텍스트"
+  side="top"           <!-- 'top'|'right'|'bottom'|'left' -->
+  align="center"       <!-- 'start'|'center'|'end' -->
+  :delay="200"
+  maxWidth="200px"
+  trigger="hover"      <!-- 'hover'|'focus'|'click'|'manual' -->
+  :disabled="false"
+>
+  <JButton>호버하세요</JButton>
+</JTooltip>
+```
 
-**권장 사용 시나리오**:
-- `open`: 모달 열림/닫힘 상태 제어
-- `size="sm"`: 작은 모달
-- `size="md"`: 중간 모달 (기본값)
-- `size="lg"`: 큰 모달
-- `size="xl"`: 매우 큰 모달
-- `size="2xl"`: 초대형 모달
-- `size="full"`: 전체 화면 모달
-- `title`: 모달 제목
-- `show-footer`: 푸터 표시 여부
-- `@confirm`: 확인 버튼 클릭 이벤트
-- `@cancel`: 취소 버튼 클릭 이벤트
-- Props 기반의 사용을 권장합니다
+---
 
-##### JFormModal - 폼 모달
+### JDivider
 
 ```vue
-<template>
-  <JFormModal 
-    :open="isOpen"
-    :schema="formSchema"
-    v-model="formData"
-    title="폼 모달"
-    @confirm="handleConfirm"
-    @cancel="handleCancel"
-  />
-</template>
+<!-- 기본 구분선 -->
+<JDivider />
 
-<script setup>
-import { ref } from 'vue'
-import { JFormModal } from '@/components/organisms'
+<!-- 텍스트 포함 구분선 -->
+<JDivider>또는</JDivider>
+```
 
-const isOpen = ref(false)
-const formData = ref({})
-const formSchema = {
-  type: 'simple',
-  fields: [
-    { controlName: 'name', label: '이름', type: 'input', isRequired: true },
-    { controlName: 'email', label: '이메일', type: 'input', inputType: 'email' },
-  ],
-}
+---
 
-const handleConfirm = () => {
-  console.log('확인:', formData.value)
-  isOpen.value = false
-}
+### JKbd
 
-const handleCancel = () => {
-  isOpen.value = false
-}
-</script>
+```vue
+<div>
+  저장: <JKbd>Ctrl</JKbd> + <JKbd>S</JKbd>
+</div>
 ```
 
-##### JHeader - 애플리케이션 헤더
+---
 
-```vue
-<template>
-  <JHeader 
-    :menu-items="menuItems"
-    :user="user"
-    @menu-click="handleMenuClick"
-  />
-</template>
+### JLabel
 
-<script setup>
-import { JHeader } from '@/components/organisms'
+```vue
+<JLabel for="input-id">이름</JLabel>
+<JInput id="input-id" v-model="name" />
+```
 
-const menuItems = [
-  { id: '1', label: '홈', path: '/' },
-  { id: '2', label: '설정', path: '/settings' },
-]
+---
 
-const user = {
-  name: '홍길동',
-  avatar: 'https://example.com/avatar.jpg',
-}
+### JLink
 
-const handleMenuClick = (item) => {
-  console.log('메뉴 클릭:', item)
-}
-</script>
+```vue
+<JLink href="/about">소개</JLink>
 ```
 
-##### JPageContainer - 페이지 컨테이너
+---
 
-```vue
-<template>
-  <JPageContainer>
-    <template #header>
-      <h1>페이지 제목</h1>
-    </template>
-    <template #content>
-      <p>페이지 내용입니다.</p>
-    </template>
-  </JPageContainer>
-</template>
+### JImage
 
-<script setup>
-import { JPageContainer } from '@/components/organisms'
-</script>
+```vue
+<JImage
+  src="https://example.com/image.jpg"
+  alt="이미지 설명"
+  width="300"
+  height="200"
+/>
 ```
 
-##### JSearchPanel - 검색 조건 패널
+---
+
+### JPopover
 
 ```vue
-<template>
-  <JSearchPanel 
-    :schema="searchSchema"
-    v-model="searchData"
-    @search="handleSearch"
-  />
-</template>
+<JPopover>
+  <template #trigger>
+    <JButton>팝오버 열기</JButton>
+  </template>
+  <template #content>
+    <div class="p-4">
+      <p>팝오버 내용입니다.</p>
+    </div>
+  </template>
+</JPopover>
+```
 
-<script setup>
-import { ref } from 'vue'
-import { JSearchPanel } from '@/components/organisms'
+---
 
-const searchData = ref({})
-const searchSchema = {
-  type: 'simple',
-  fields: [
-    { controlName: 'keyword', label: '검색어', type: 'input' },
-    { controlName: 'category', label: '카테고리', type: 'combo', options: [] },
-  ],
-}
+### JSpinner
 
-const handleSearch = (data) => {
-  console.log('검색:', data)
-}
-</script>
+```vue
+<JSpinner v-if="loading" />
+<div v-else>콘텐츠</div>
 ```
 
-##### JSidebarAdvanced - 고급 사이드바
+---
 
-```vue
-<template>
-  <JSidebarAdvanced 
-    :menu-items="menuItems"
-    :favorites="favorites"
-    @menu-click="handleMenuClick"
-  />
-</template>
+### JTree
 
-<script setup>
-import { JSidebarAdvanced } from '@/components/organisms'
+```vue
+<JTree
+  :items="treeItems"
+  v-model:expanded-keys="expandedKeys"
+  v-model:active-key="activeKey"
+  :permissions="permissions"
+  :max-depth="10"
+  searchQuery=""
+  @node-click="handleNodeClick"
+  @expand-change="handleExpandChange"
+/>
+```
 
-const menuItems = [
-  { id: '1', label: '홈', path: '/', icon: 'house' },
-  { id: '2', label: '설정', path: '/settings', icon: 'settings' },
-]
+---
 
-const favorites = ['1']
+## Molecules Props 레퍼런스
 
-const handleMenuClick = (item) => {
-  console.log('메뉴 클릭:', item)
-}
-</script>
-```
+### JFormField
 
-##### JSidebarSimple - 간단한 사이드바
+> **권장**: 폼 필드 구성 시 JFormField 사용. `type` prop으로 입력 컴포넌트 선택.
 
 ```vue
-<template>
-  <JSidebarSimple 
-    :menu-items="menuItems"
-    @menu-click="handleMenuClick"
-  />
-</template>
+<JFormField
+  type="input"           <!-- 'input'|'textarea'|'checkbox'|'switch'|'combo'|'radio'|'searchCombo'|'datepicker' -->
+  label="이름"
+  description="설명 텍스트"
+  error-msg="에러 메시지"
+  v-model="value"
+  placeholder="입력하세요"
+  :required="true"
+  :disabled="false"
+  :readonly="false"
+  orientation="vertical"  <!-- 'vertical'|'horizontal'|'responsive' -->
+  labelAlign="left"       <!-- 'left'|'middle'|'right' -->
+  labelWidth="8rem"
+  inputType="text"        <!-- type="input"일 때: 'text'|'email'|'password'|'number' -->
+  :options="[]"           <!-- type이 combo/radio/searchCombo일 때 -->
+  :multiple="false"       <!-- type이 combo/searchCombo일 때 -->
+  radioDirection="horizontal"  <!-- type="radio"일 때: 'horizontal'|'vertical' -->
+/>
+```
 
-<script setup>
-import { JSidebarSimple } from '@/components/organisms'
+**장점:**
+- `label` prop → 라벨 자동 배치 + 접근성 연결
+- `error-msg` prop → 에러 메시지 자동 표시
+- `orientation` → 레이아웃 일관성
 
-const menuItems = [
-  { id: '1', label: '홈', path: '/' },
-  { id: '2', label: '설정', path: '/settings' },
-]
+---
 
-const handleMenuClick = (item) => {
-  console.log('메뉴 클릭:', item)
-}
-</script>
+### JCard
+
+```vue
+<JCard title="카드 제목" description="설명" footer="푸터">
+  <p>카드 내용</p>
+</JCard>
 ```
 
 ---
 
-## 고급 사용법
+### JAlert
 
-### JToast/JToaster 사용법
+```vue
+<JAlert
+  variant="default"     <!-- 'default'|'destructive' -->
+  title="알림"
+  description="메시지 내용"
+  buttonText="확인"
+  :showFooter="true"
+  @confirm="handler"
+/>
+```
 
-Toast 알림은 전역적으로 메시지를 표시하는 데 사용됩니다. `JToast` 함수와 `JToaster` 컴포넌트를 함께 사용합니다.
+**Slots**: `header`, default, `footer`
 
-#### 설치 및 설정
+---
 
-앱의 루트 레벨에 `<JToaster />` 컴포넌트를 추가해야 합니다:
+### JTabs
 
 ```vue
-<template>
-  <RouterView />
-  <JToaster />
-</template>
+<JTabs
+  :tabs="[
+    { id: 'tab1', label: '탭 1', closable: false },
+    { id: 'tab2', label: '탭 2', closable: true },
+  ]"
+  v-model:active-tab-id="activeTab"
+  @tab-change="handler"
+  @tab-close="handler"
+>
+  <template #content-tab1>탭 1 내용</template>
+  <template #content-tab2>탭 2 내용</template>
+</JTabs>
+```
 
-<script setup>
-import { JToaster } from '@/components/atoms'
-// 또는 NPM 패키지 사용 시
-// import { JToaster } from '@j-solution/components'
-</script>
+---
+
+### JAccordion
+
+```vue
+<JAccordion
+  :items="[
+    { value: 'item-1', title: '제목 1', content: '내용 1' },
+    { value: 'item-2', title: '제목 2', content: '내용 2' },
+  ]"
+  type="single"
+  collapsible
+/>
 ```
 
-#### 기본 사용법
+---
+
+### JBreadcrumb
 
 ```vue
-<script setup>
-import { JToast } from '@/components/atoms'
-// 또는 NPM 패키지 사용 시
-// import { JToast } from '@j-solution/components'
+<JBreadcrumb :items="[
+  { label: '홈', href: '/' },
+  { label: '카테고리', href: '/category' },
+  { label: '현재 페이지' },
+]" />
+```
 
-// 기본 Toast
-const showToast = () => {
-  JToast('메시지가 표시됩니다')
-}
+---
 
-// Success Toast
-const showSuccess = () => {
-  JToast.success('성공적으로 저장되었습니다')
-}
+### JButtonGroup
 
-// Error Toast
-const showError = () => {
-  JToast.error('오류가 발생했습니다')
-}
+```vue
+<JButtonGroup>
+  <JButton>저장</JButton>
+  <JButton>취소</JButton>
+  <JButton>삭제</JButton>
+</JButtonGroup>
+```
 
-// Info Toast
-const showInfo = () => {
-  JToast.info('정보 메시지입니다')
-}
+---
 
-// Warning Toast
-const showWarning = () => {
-  JToast.warning('경고 메시지입니다')
-}
-</script>
+### JTitlebar
+
+```vue
+<JTitlebar title="페이지 제목" description="설명">
+  <template #actions>
+    <JButton>액션</JButton>
+  </template>
+</JTitlebar>
 ```
 
-#### 고급 사용법
+---
+
+### JContextMenu
 
 ```vue
-<script setup>
-import { JToast } from '@/components/atoms'
+<JContextMenu :items="menuGroups" :disabled="false" @select="handler">
+  <div>우클릭 영역</div>
+</JContextMenu>
+```
 
-// Description이 있는 Toast
-const showWithDescription = () => {
-  JToast('제목', {
-    description: '추가 설명 텍스트',
-  })
-}
+---
 
-// Action 버튼이 있는 Toast
-const showWithAction = () => {
-  JToast('제목', {
-    description: '설명 텍스트',
-    action: {
-      label: '실행 취소',
-      onClick: () => {
-        console.log('실행 취소')
-      },
-    },
-  })
-}
+### JGroupCombo
 
-// Promise Toast (비동기 작업 표시)
-const showPromiseToast = async () => {
-  await JToast.promise(
-    fetch('/api/data').then(res => res.json()),
+```vue
+<JGroupCombo
+  v-model="selected"
+  :groups="[
     {
-      loading: '로딩 중...',
-      success: (data) => `${data.name}이(가) 생성되었습니다`,
-      error: '오류가 발생했습니다',
-    }
-  )
-}
-</script>
+      label: '그룹 1',
+      options: [
+        { value: '1-1', label: '옵션 1-1' },
+        { value: '1-2', label: '옵션 1-2' },
+      ],
+    },
+    {
+      label: '그룹 2',
+      options: [
+        { value: '2-1', label: '옵션 2-1' },
+      ],
+    },
+  ]"
+  placeholder="그룹에서 선택하세요"
+/>
 ```
 
-**주요 특징:**
-- `JToast`: Toast 메시지를 표시하는 함수 (`JToast.success()`, `JToast.error()` 등)
-- `JToaster`: Toast를 렌더링하는 컨테이너 컴포넌트 (`<JToaster />`)
-- 자동 사라짐: 기본적으로 몇 초 후 자동으로 사라집니다
-- 여러 Toast 동시 표시 가능
-- 위치 설정 가능: `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`
-
-### JFormField 사용 권장사항
+---
 
-폼 필드를 만들 때는 `JFormField`를 사용하세요. `label`, `error-msg` prop으로 값을 입력하면 UI 배치시 라벨과 에러 메시지가 포함됩니다. `type` prop으로 원하는 입력 컴포넌트를 선택할 수 있습니다:
+### JSearchAddr
 
 ```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>
+<JSearchAddr
+  v-model="address"
+  @select="handleAddressSelect"
+/>
 ```
 
-**장점:**
-- `type` prop으로 다양한 입력 컴포넌트 선택 가능 (input, textarea, combo, datepicker 등)
-- `label` prop으로 라벨 값을 입력하면 UI 배치시 라벨이 포함되며, 입력 필드와 자동 연결 (접근성)
-- `error-msg` prop으로 에러 메시지 값을 입력하면 UI 배치시 에러 메시지가 포함됨
-- 레이아웃 일관성 유지
+---
 
-### JDynamicForm 사용 권장사항
+## Organisms Props 레퍼런스
 
-JSON 스키마로 폼을 자동 생성할 수 있습니다:
+### JModal
 
 ```vue
-<template>
-  <JDynamicForm 
-    :schema="formSchema" 
-    v-model="formData"
-    @submit="handleSubmit"
-  />
-</template>
+<JModal
+  :open="isOpen"
+  title="모달 제목"
+  description="설명"
+  size="md"              <!-- 'sm'|'md'|'lg'|'xl'|'2xl'|'full' -->
+  buttonType="OkCancel"  <!-- 'Ok'|'OkCancel' -->
+  confirmText="확인"
+  cancelText="취소"
+  confirmVariant="default"  <!-- 'default'|'destructive'|'outline'|'secondary'|'ghost'|'link' -->
+  :confirmDisabled="false"
+  :showFormField="false"
+  formFieldType="input"     <!-- 'input'|'textarea'|'checkbox'|'switch'|'combo'|'radio'|'searchCombo'|'datepicker' -->
+  formFieldLabel="필드 라벨"
+  formFieldInputType="text"
+  formFieldInputPlaceholder="입력"
+  :formFieldRequired="false"
+  :formFieldValue="''"
+  formFieldError=""
+  @confirm="handler"     <!-- showFormField일 때 입력값 전달 -->
+  @cancel="handler"
+  @update:open="handler"
+>
+  <template #body>
+    커스텀 내용
+  </template>
+</JModal>
+```
 
-<script setup>
+---
+
+### JDynamicForm
+
+```vue
+<JDynamicForm
+  :schema="formSchema"
+  v-model="formData"
+  @submit="handler"
+  @change="handler"      <!-- { field, value } -->
+  @error="handler"
+/>
+```
+
+```ts
 const formSchema = {
   type: 'simple',  // 'simple' | 'sectioned' | 'wizard'
   fields: [
     {
-      controlName: 'name',
+      controlName: 'name',       // 필드 키
       label: '이름',
-      type: 'input',
-      isRequired: true
+      type: 'input',             // 'input'|'textarea'|'checkbox'|'switch'|'combo'|'radio'|'searchCombo'|'datepicker'
+      isRequired: true,
+      inputType: 'text',         // type='input'일 때
+      placeholder: '이름 입력',
+      options: [],               // combo/radio/searchCombo일 때
+      disabled: false,
     },
+  ],
+  // sectioned 타입일 때
+  sections: [
     {
-      controlName: 'email',
-      label: '이메일',
-      type: 'input',
-      inputType: 'email'
-    }
-  ]
+      title: '섹션 제목',
+      fields: [/* fields 배열 */],
+    },
+  ],
 }
-</script>
 ```
 
-**권장 사용:**
-- `simple`: 단순한 폼
-- `sectioned`: 섹션별로 구분된 폼
-- `wizard`: 단계별 입력 폼
+---
+
+### JFormModal
+
+```vue
+<JFormModal
+  :open="isOpen"
+  :schema="formSchema"
+  v-model="formData"
+  title="폼 모달"
+  size="md"
+  @confirm="handler"
+  @cancel="handler"
+/>
+```
 
-### JDynamicTabs - 경로 기반 컴포넌트 로딩
+---
 
-`JDynamicTabs`는 런타임에 탭을 동적으로 추가/제거할 수 있는 컴포넌트입니다. 경로(`/user/info` 같은)만 가지고 있을 때 해당 경로의 Vue 컴포넌트를 탭 콘텐츠로 표시하는 방법에 대한 가이드입니다.
+### JSearchPanel
 
-#### 핵심 원칙
+```vue
+<JSearchPanel
+  title="조회조건"
+  :schema="searchSchema"
+  v-model="searchData"
+  :defaultCollapsed="false"
+  :collapsible="true"
+  @submit="handleSearch"
+  @reset="handleReset"
+/>
+```
 
-**Route 통일성을 최우선으로 고려해야 합니다.**
+> 비어있지 않은 필드는 조건 뱃지로 표시, 개별 필드 초기화 지원
 
-- ✅ Router가 있는 프로젝트: Router의 routes를 재사용하여 통일성 보장
-- ✅ Router가 없는 프로젝트: 독립적인 컴포넌트 로딩 방식 사용
+---
 
-#### 방법 1: RouterView 사용 (Router가 있는 경우) ⭐ 권장
+### JDynamicTabs
 
-#### 언제 사용
-- 프로젝트에 Vue Router가 설치되어 있는 경우
-- Router의 routes에 경로-컴포넌트 매핑이 이미 정의되어 있는 경우
-- Route 통일성을 보장해야 하는 경우
+```vue
+<JDynamicTabs
+  ref="tabsRef"
+  :initial-tabs="initialTabs"
+  defaultActiveId="tab1"
+  :maxTabs="0"           <!-- 0 = 무제한 -->
+  emptyMessage="탭을 추가해주세요."
+  @tab-add="handler"
+  @tab-change="handler"
+  @tab-close="handler"
+>
+  <template #content-tab1>내용</template>
+</JDynamicTabs>
+```
 
-#### 장점
-- ✅ **Route 통일성 보장**: Router의 routes를 재사용하므로 경로-컴포넌트 매핑 중복 없음
-- ✅ URL 동기화 자동: 브라우저 뒤로가기 지원
-- ✅ 라우트 가드 활용: Router의 네비게이션 가드 사용 가능
-- ✅ 코드 스플리팅 자동: Router의 lazy loading 활용
-- ✅ 유지보수 용이: Router 설정만 수정하면 됨
+**Exposed 메서드:**
+- `tabsRef.value?.addTab({ id, label, closable, meta })`
+- `tabsRef.value?.closeTab(id)`
+- `tabsRef.value?.activateTab(id)`
+- `tabsRef.value?.closeAllTabs()`
 
-#### 단점
-- Router 의존적: Vue Router 필수
-- RouterView는 Router의 현재 경로를 사용하므로, 각 탭에 독립적인 경로를 보장하려면 Router 관리 필요
+---
 
-#### 사용 예제
+### JHeader
 
 ```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>
+<JHeader
+  :menu-items="menuItems"
+  :user="{ name: '홍길동', avatar: 'https://example.com/avatar.jpg' }"
+  @menu-click="handler"
+/>
+```
 
-<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[]>([])
+### JPageContainer
 
-// 메뉴 클릭 시 탭 추가
-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>
+```vue
+<JPageContainer>
+  <template #header>
+    <h1>페이지 제목</h1>
+  </template>
+  <template #content>
+    <p>페이지 내용</p>
+  </template>
+</JPageContainer>
 ```
 
-#### 방법 2: 경로 기반 동적 import (Router가 없는 경우)
+---
 
-#### 언제 사용
-- 프로젝트에 Vue Router가 설치되어 있지 않은 경우
-- Router의 routes와 완전히 독립적인 경로가 필요한 경우
-- Router 없이도 동작해야 하는 경우
+### JSidebarSimple
 
-#### 장점
-- ✅ Router 독립적: Vue Router 없이도 사용 가능
-- ✅ 가벼움: 불필요한 라우팅 로직 없음
-- ✅ 코드 스플리팅 자동: 동적 import로 성능 최적화
-- ✅ 세밀한 제어: 탭별 독립적인 컴포넌트 관리
+```vue
+<JSidebarSimple
+  :menu-items="[
+    { id: '1', label: '홈', path: '/' },
+    { id: '2', label: '설정', path: '/settings' },
+  ]"
+  @menu-click="handler"
+/>
+```
 
-#### 단점
-- ❌ Router의 routes와 중복 정의 필요
-- ❌ Route 통일성 보장 어려움
-- ❌ 경로 변경 시 두 곳 모두 수정 필요 (Router가 나중에 추가되는 경우)
+---
 
-#### 사용 예제
+### JSidebarAdvanced
 
 ```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>
+<JSidebarAdvanced
+  :menu-items="[
+    { id: '1', label: '홈', path: '/', icon: 'house' },
+    { id: '2', label: '설정', path: '/settings', icon: 'settings' },
+  ]"
+  :favorites="['1']"
+  @menu-click="handler"
+/>
+```
 
-<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' }, '해당 경로의 컴포넌트를 매핑에 추가하세요.'),
-    ])
-  }
-}
+## Templates Props 레퍼런스
 
-// 메뉴 클릭 시 탭 추가
-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>
+### JLayout
+
+```vue
+<JLayout>
+  <template #header>
+    <JHeader :menu-items="menuItems" />
+  </template>
+  <template #sidebar>
+    <JSidebarSimple :menu-items="menuItems" />
+  </template>
+  <template #content>
+    <RouterView />
+  </template>
+</JLayout>
 ```
 
-#### 선택 가이드 (Decision Tree)
+---
+
+### JLayoutSimple
 
+```vue
+<JLayoutSimple
+  :menu-items="menuItems"
+  :permissions="permissions"
+  :contentScroll="true"
+>
+  <template #content>
+    <YourPageContent />
+  </template>
+</JLayoutSimple>
 ```
-프로젝트에 Vue Router가 있나요?
-│
-├─ 예 → 방법 1 (RouterView 또는 Router의 routes 재사용)
-│       ✅ Route 통일성 보장
-│       ✅ 중복 정의 없음
-│       ✅ 유지보수 용이
-│
-└─ 아니오 → 방법 2 (동적 import)
-            ✅ Router 독립적
-            ✅ 가벼움
-            ⚠️ 나중에 Router 추가 시 중복 주의
-```
 
-#### 주의사항
+**Slots**: `header`, `sidebar`, `content`
+
+---
 
-##### ⚠️ 방법 2를 사용 중인 프로젝트에서 Router 추가 시
+### JLayoutAdvanced
 
-프로젝트에 나중에 Vue Router를 추가하는 경우:
+```vue
+<JLayoutAdvanced
+  :menu-items="menuItems"
+  :favorites="favorites"
+  :permissions="permissions"
+  :contentScroll="true"
+  @menu-click="handler"
+  @tab-add="handler"
+  @tab-change="handler"
+  @tab-close="handler"
+  @favorite-change="handler"
+>
+  <template #content-tab-{id}>
+    <RouterView />
+  </template>
+</JLayoutAdvanced>
+```
 
-1. **즉시 방법 1로 마이그레이션 권장**
-   - Router의 routes를 재사용하여 통일성 보장
-   - 중복 정의 제거
+**Slots**: `header`, `sidebar`, `content`, `content-tab-{id}`
 
-2. **마이그레이션이 어려운 경우**
-   - Router의 routes와 `componentMap`을 동기화 유지
-   - 경로 변경 시 두 곳 모두 수정
+---
 
-##### ⚠️ 방법 1 사용 시 주의사항
+## Toast 사용법
 
-- RouterView는 Router의 현재 경로를 사용하므로, 각 탭에 독립적인 경로를 보장하려면 Router 관리 필요
-- 탭 내부에서 라우터 이동 시 전체 앱의 경로가 변경됨 (이를 방지하려면 추가 로직 필요)
+```vue
+<!-- 루트에 JToaster 추가 -->
+<template>
+  <RouterView />
+  <JToaster />
+</template>
+```
 
-#### 요약
+```ts
+import { JToast } from '@/components/atoms'
 
-| 항목 | 방법 1 (RouterView) | 방법 2 (동적 import) |
-|------|---------------------|---------------------|
-| **Router 필요** | 필수 | 불필요 |
-| **Route 통일성** | ✅ 보장 (Router routes 재사용) | ❌ 보장 어려움 (중복 정의 필요) |
-| **중복 코드** | 없음 | 경로-컴포넌트 매핑 중복 |
-| **유지보수** | Router만 수정 | 두 곳 모두 수정 필요 |
-| **권장 상황** | Router가 있는 경우 ⭐ | Router가 없는 경우 |
+JToast('기본 메시지')
+JToast.success('성공')
+JToast.error('오류')
+JToast.info('정보')
+JToast.warning('경고')
+
+// 옵션
+JToast('제목', { description: '설명', action: { label: '취소', onClick: () => {} } })
+
+// Promise
+JToast.promise(fetchData(), {
+  loading: '로딩 중...',
+  success: (data) => `완료: ${data.name}`,
+  error: '오류 발생',
+})
+```
 
 ---
 
-## 레이아웃 템플릿 가이드
-
-템플릿 컴포넌트는 전체 페이지 레이아웃을 구성하는 데 사용됩니다. 프로젝트의 요구사항에 따라 적절한 템플릿을 선택하세요.
+## 상황별 추천 컴포넌트
+
+| 상황 | 컴포넌트 |
+|------|---------|
+| 단일 텍스트 입력 | `JInput` |
+| 여러 줄 텍스트 | `JTextarea` |
+| 날짜 선택 | `JDatepicker` |
+| 옵션 적은 단일 선택 | `JCombo` |
+| 옵션 많은 단일 선택 | `JSearchCombo` |
+| 다중 선택 드롭다운 | `JCombo` `:multiple="true"` |
+| ON/OFF 토글 | `JSwitch` |
+| 체크박스 | `JCheckbox` |
+| 라디오 선택 | `JRadio` |
+| 라벨+에러 포함 폼 필드 | `JFormField` |
+| 스키마 기반 폼 생성 | `JDynamicForm` |
+| 데이터 테이블 | `JGrid` |
+| 모달 다이얼로그 | `JModal` |
+| 폼 모달 | `JFormModal` |
+| 검색 조건 패널 | `JSearchPanel` |
+| 전역 알림 | `JToast` + `JToaster` |
+| 탭 전환 (정적) | `JTabs` |
+| 탭 전환 (동적) | `JDynamicTabs` |
+| 트리 뷰 | `JTree` |
+| 전체 레이아웃 (탭 기반) | `JLayoutAdvanced` |
+| 전체 레이아웃 (단일 페이지) | `JLayoutSimple` |
 
-### JLayout - 기본 레이아웃
+---
 
-커스텀 레이아웃을 구성할 때 사용합니다.
+## 주의사항
 
-```vue
-<template>
-  <JLayout>
-    <template #header>
-      <JHeader :menu-items="menuItems" />
-    </template>
-    <template #sidebar>
-      <JSidebarSimple :menu-items="menuItems" />
-    </template>
-    <template #content>
-      <RouterView />
-    </template>
-  </JLayout>
-</template>
+1. **JCheckbox / JSwitch의 modelValue는 `'Y'` / `'N'` 문자열** (boolean 아님)
+2. **JSearchCombo의 modelValue는 `{ value, label }` 객체** (string 아님)
+3. **JRadio는 `options` 배열**로 항목 정의 (개별 나열 아님)
+4. **JDatepicker의 modelValue는 `string | null`** (ISO 8601: `'YYYY-MM-DD'`)
+5. **JGrid의 AG Grid Enterprise 기능** (`enableGrouping`, `enablePivot`, `enableExcelExport`)은 라이선스 필요
+6. **JDynamicForm 스키마의 필드 `type`과 JFormField의 `type`은 동일한 값 사용**
 
-<script setup>
-import { JLayout, JHeader, JSidebarSimple } from '@/components'
-</script>
-```
+---
 
-### JLayoutAdvanced 사용 시
+## JDynamicTabs 경로 기반 컴포넌트 로딩
 
-- 탭 기반 멀티 페이지 애플리케이션
-- 메뉴 클릭 시 자동 탭 생성
-- 검색, 즐겨찾기 기능 필요
-- 권한 관리 필요
+### 방법 1: RouterView (Router 있는 경우) — 권장
 
 ```vue
 <template>
-  <JLayoutAdvanced 
-    :menu-items="menuItems"
-    :favorites="favorites"
-    :permissions="permissions"
-  >
-    <template #content-tab-{id}>
-      <RouterView />
+  <JDynamicTabs ref="tabsRef" :initial-tabs="initialTabs">
+    <template v-for="tab in allTabs" :key="tab.id" #[`content-${tab.id}`]>
+      <RouterView v-if="tab.meta?.path" :key="tab.id" />
     </template>
-  </JLayoutAdvanced>
+  </JDynamicTabs>
 </template>
 
 <script setup>
-import { JLayoutAdvanced } from '@/components'
+import { ref } from 'vue'
+import { useRouter } from 'vue-router'
+
+const router = useRouter()
+const tabsRef = ref()
+const allTabs = ref([])
+
+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 } })
+  router.push({ path: item.path })
+}
 </script>
 ```
 
-### JLayoutSimple 사용 시
-
-- 단일 페이지 애플리케이션
-- 간단한 메뉴 구조
-- 검색 기능만 필요
+### 방법 2: 동적 import (Router 없는 경우)
 
 ```vue
-<template>
-  <JLayoutSimple :menu-items="menuItems">
-    <template #content>
-      <YourPageContent />
-    </template>
-  </JLayoutSimple>
-</template>
-
 <script setup>
-import { JLayoutSimple } from '@/components'
+import { defineAsyncComponent } from 'vue'
+
+const componentMap = {
+  '/user/info': () => import('@/pages/UserInfo.vue'),
+  '/user/list': () => import('@/pages/UserList.vue'),
+}
+
+const loadComponentByPath = (path) => {
+  if (componentMap[path]) return defineAsyncComponent({ loader: componentMap[path] })
+  return { setup: () => () => h('div', `경로 미등록: ${path}`) }
+}
 </script>
 ```
 
-> 💡 **레이아웃 컴포넌트 상세 정보**: [LAYOUT_TEMPLATE_GUIDE.md](./LAYOUT_TEMPLATE_GUIDE.md)를 참고하세요.
+**선택 기준**: Router 있으면 방법 1, 없으면 방법 2
 
 ---
 
-**문서 버전**: v1.2.1  
+**문서 버전**: v1.3.0
 **최종 업데이트**: 2025년 12월
-