@j-solution/components 1.1.0 → 1.2.0

package/USAGE_GUIDE.md

@@ -59,7 +59,7 @@ import { JButton } from '@/components'
 
 ## 컴포넌트 목록
 
-### Atoms (원자) - 22개
+### Atoms (원자) - 25개
 
 기본적인 UI 요소들로, 더 이상 분해할 수 없는 최소 단위의 컴포넌트입니다.
 
@@ -72,6 +72,7 @@ import { JButton } from '@/components'
 | **JCombo** | 드롭다운 선택 | 단일/다중 선택 |
 | **JDatepicker** | 날짜 선택기 | 날짜 입력 |
 | **JDivider** | 구분선 | 콘텐츠 구분 |
+| **JEditor** | 마크다운 에디터 | 마크다운 문서 작성 |
 | **JGrid** | 데이터 그리드 | 테이블 데이터 표시 (AG Grid 기반) |
 | **JIcon** | 아이콘 | 시각적 표시 |
 | **JImage** | 이미지 | 이미지 표시 |
@@ -80,12 +81,14 @@ import { JButton } from '@/components'
 | **JLabel** | 라벨 | 폼 필드 라벨 |
 | **JLink** | 링크 | 네비게이션 |
 | **JPopover** | 팝오버 | 추가 정보 표시 |
+| **JPreview** | 마크다운/HTML 뷰어 | 마크다운 또는 HTML 문서 표시 |
 | **JProgress** | 진행률 표시 | 작업 진행 상태 |
 | **JRadio** | 라디오 버튼 | 단일 선택 |
 | **JSearchCombo** | 검색 가능한 드롭다운 | 많은 옵션 중 검색 선택 |
 | **JSpinner** | 로딩 스피너 | 로딩 상태 표시 |
 | **JSwitch** | 토글 스위치 | ON/OFF 설정 |
 | **JTextarea** | 멀티라인 텍스트 입력 | 여러 라인 텍스트 입력 |
+| **JToaster** | Toast 알림 컨테이너 | 전역 알림 메시지 표시 |
 | **JTooltip** | 툴팁 | 추가 설명 표시 |
 
 ### Molecules (분자) - 11개
@@ -278,6 +281,7 @@ Templates (템플릿)
 | 상황 | 추천 컴포넌트 | 이유 |
 |------|--------------|------|
 | 성공/경고/에러 메시지 | `JAlert` | 타입별 스타일 자동 적용 |
+| 전역 알림 메시지 (Toast) | `JToast` (함수) + `JToaster` (컴포넌트) | 화면 상단/하단에 일시적으로 표시되는 알림 |
 | 추가 설명 | `JTooltip` | 호버 시 설명 표시 |
 | 추가 정보 | `JPopover` | 클릭 시 정보 표시 |
 
@@ -352,6 +356,1018 @@ const enabled = ref(false)
 </script>
 ```
 
+### 이벤트 처리
+
+컴포넌트는 표준 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>
+```
+
+### 컴포넌트별 기본 사용법
+
+#### Atoms (원자 컴포넌트)
+
+##### JAvatar - 사용자 아바타
+
+```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>
+```
+
+##### 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 - 체크박스
+
+```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 - 드롭다운 선택
+
+```vue
+<template>
+  <JCombo 
+    v-model="selected" 
+    :options="options"
+    placeholder="선택하세요"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { JCombo } from '@/components/atoms'
+
+const selected = ref('')
+const options = [
+  { value: 'option1', label: '옵션 1' },
+  { value: 'option2', label: '옵션 2' },
+  { value: 'option3', label: '옵션 3' },
+]
+</script>
+```
+
+##### JDatepicker - 날짜 선택기
+
+```vue
+<template>
+  <JDatepicker 
+    v-model="date"
+    placeholder="날짜를 선택하세요"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { JDatepicker } from '@/components/atoms'
+
+const date = ref(null)
+</script>
+```
+
+##### JDivider - 구분선
+
+```vue
+<template>
+  <div>위쪽 콘텐츠</div>
+  <JDivider />
+  <div>아래쪽 콘텐츠</div>
+  
+  <!-- 텍스트와 함께 사용 -->
+  <JDivider>또는</JDivider>
+</template>
+
+<script setup>
+import { JDivider } from '@/components/atoms'
+</script>
+```
+
+##### 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>
+```
+
+##### JIcon - 아이콘
+
+```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>
+```
+
+##### JImage - 이미지
+
+```vue
+<template>
+  <JImage 
+    src="https://example.com/image.jpg"
+    alt="이미지 설명"
+    width="300"
+    height="200"
+  />
+</template>
+
+<script setup>
+import { JImage } from '@/components/atoms'
+</script>
+```
+
+##### 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>
+```
+
+##### JLabel - 라벨
+
+```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>
+```
+
+##### 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>
+```
+
+##### 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 - 라디오 버튼
+
+```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>
+```
+
+##### 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 - 로딩 스피너
+
+```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>
+```
+
+##### 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>
+```
+
+##### 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 - 툴팁
+
+```vue
+<template>
+  <JTooltip content="이것은 툴팁입니다">
+    <JButton>호버하세요</JButton>
+  </JTooltip>
+</template>
+
+<script setup>
+import { JTooltip, JButton } from '@/components/atoms'
+</script>
+```
+
+##### 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: '두 번째 항목의 내용입니다.',
+  },
+]
+</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 handleConfirm = () => {
+  console.log('확인 클릭')
+}
+</script>
+```
+
+##### JBreadcrumb - 페이지 네비게이션 경로
+
+```vue
+<template>
+  <JBreadcrumb :items="breadcrumbItems" />
+</template>
+
+<script setup>
+import { JBreadcrumb } from '@/components/molecules'
+
+const breadcrumbItems = [
+  { label: '홈', href: '/' },
+  { label: '카테고리', href: '/category' },
+  { label: '현재 페이지' },
+]
+</script>
+```
+
+##### JButtonGroup - 버튼 그룹
+
+```vue
+<template>
+  <JButtonGroup>
+    <JButton>저장</JButton>
+    <JButton>취소</JButton>
+    <JButton>삭제</JButton>
+  </JButtonGroup>
+</template>
+
+<script setup>
+import { JButtonGroup, JButton } from '@/components/molecules'
+</script>
+```
+
+##### JCard - 카드 컴포넌트
+
+```vue
+<template>
+  <JCard 
+    title="카드 제목"
+    description="카드 설명"
+    footer="푸터 텍스트"
+  >
+    <p>카드 내용입니다.</p>
+  </JCard>
+</template>
+
+<script setup>
+import { JCard } from '@/components/molecules'
+</script>
+```
+
+##### JContextMenu - 우클릭 컨텍스트 메뉴
+
+```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>
+```
+
+##### 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 - 주소 검색
+
+```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>
+```
+
+##### 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 - 타이틀바
+
+```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>
+```
+
+##### JFormField - 폼 필드 래퍼
+
+**주요 props**: `type` (input, textarea, checkbox, switch, combo, radio, searchCombo, datepicker), `label`, `description`, `errorMsg`, `modelValue`, `placeholder`, `disabled`, `required`, `orientation` (vertical, horizontal, responsive), `labelAlign`, `labelWidth`
+
+**권장 사용 시나리오**:
+- `type` prop으로 원하는 입력 컴포넌트 선택
+- `label` prop으로 라벨 값을 입력하면 UI 배치시 라벨이 포함되며, 입력 필드와 자동 연결 (접근성)
+- `errorMsg` prop으로 에러 메시지 값을 입력하면 UI 배치시 에러 메시지가 포함됨
+- `orientation="horizontal"`: 레이블과 입력 필드를 가로로 배치
+- `orientation="vertical"`: 레이블과 입력 필드를 세로로 배치 (기본값)
+- `orientation="responsive"`: 화면 크기에 따라 자동 조정
+- 레이아웃 일관성 유지
+
+#### Organisms (유기체 컴포넌트)
+
+##### JDynamicForm - 스키마 기반 동적 폼
+
+**주요 props**: `schema` (JSON 스키마), `modelValue`, `type` (simple, sectioned, wizard)
+
+**권장 사용 시나리오**:
+- `type="simple"`: 단순한 폼
+- `type="sectioned"`: 섹션별로 구분된 폼
+- `type="wizard"`: 단계별 입력 폼
+- JSON 스키마로 폼 자동 생성
+- `schema.fields` 배열에 필드 정의: `controlName`, `label`, `type`, `isRequired` 등
+- Props 기반의 사용을 권장합니다
+
+##### JModal - 모달 다이얼로그
+
+**주요 props**: `open`, `size` (sm, md, lg, xl, 2xl, full), `title`, `description`, `show-footer`, `confirm-text`, `cancel-text`
+
+**권장 사용 시나리오**:
+- `open`: 모달 열림/닫힘 상태 제어
+- `size="sm"`: 작은 모달
+- `size="md"`: 중간 모달 (기본값)
+- `size="lg"`: 큰 모달
+- `size="xl"`: 매우 큰 모달
+- `size="2xl"`: 초대형 모달
+- `size="full"`: 전체 화면 모달
+- `title`: 모달 제목
+- `show-footer`: 푸터 표시 여부
+- `@confirm`: 확인 버튼 클릭 이벤트
+- `@cancel`: 취소 버튼 클릭 이벤트
+- Props 기반의 사용을 권장합니다
+
+##### JFormModal - 폼 모달
+
+```vue
+<template>
+  <JFormModal 
+    :open="isOpen"
+    :schema="formSchema"
+    v-model="formData"
+    title="폼 모달"
+    @confirm="handleConfirm"
+    @cancel="handleCancel"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { JFormModal } from '@/components/organisms'
+
+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
+}
+
+const handleCancel = () => {
+  isOpen.value = false
+}
+</script>
+```
+
+##### JHeader - 애플리케이션 헤더
+
+```vue
+<template>
+  <JHeader 
+    :menu-items="menuItems"
+    :user="user"
+    @menu-click="handleMenuClick"
+  />
+</template>
+
+<script setup>
+import { JHeader } from '@/components/organisms'
+
+const menuItems = [
+  { id: '1', label: '홈', path: '/' },
+  { id: '2', label: '설정', path: '/settings' },
+]
+
+const user = {
+  name: '홍길동',
+  avatar: 'https://example.com/avatar.jpg',
+}
+
+const handleMenuClick = (item) => {
+  console.log('메뉴 클릭:', item)
+}
+</script>
+```
+
+##### JPageContainer - 페이지 컨테이너
+
+```vue
+<template>
+  <JPageContainer>
+    <template #header>
+      <h1>페이지 제목</h1>
+    </template>
+    <template #content>
+      <p>페이지 내용입니다.</p>
+    </template>
+  </JPageContainer>
+</template>
+
+<script setup>
+import { JPageContainer } from '@/components/organisms'
+</script>
+```
+
+##### JSearchPanel - 검색 조건 패널
+
+```vue
+<template>
+  <JSearchPanel 
+    :schema="searchSchema"
+    v-model="searchData"
+    @search="handleSearch"
+  />
+</template>
+
+<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: [] },
+  ],
+}
+
+const handleSearch = (data) => {
+  console.log('검색:', data)
+}
+</script>
+```
+
+##### JSidebarAdvanced - 고급 사이드바
+
+```vue
+<template>
+  <JSidebarAdvanced 
+    :menu-items="menuItems"
+    :favorites="favorites"
+    @menu-click="handleMenuClick"
+  />
+</template>
+
+<script setup>
+import { JSidebarAdvanced } from '@/components/organisms'
+
+const menuItems = [
+  { id: '1', label: '홈', path: '/', icon: 'house' },
+  { id: '2', label: '설정', path: '/settings', icon: 'settings' },
+]
+
+const favorites = ['1']
+
+const handleMenuClick = (item) => {
+  console.log('메뉴 클릭:', item)
+}
+</script>
+```
+
+##### JSidebarSimple - 간단한 사이드바
+
+```vue
+<template>
+  <JSidebarSimple 
+    :menu-items="menuItems"
+    @menu-click="handleMenuClick"
+  />
+</template>
+
+<script setup>
+import { JSidebarSimple } from '@/components/organisms'
+
+const menuItems = [
+  { id: '1', label: '홈', path: '/' },
+  { id: '2', label: '설정', path: '/settings' },
+]
+
+const handleMenuClick = (item) => {
+  console.log('메뉴 클릭:', item)
+}
+</script>
+```
+
+---
+
+## 고급 사용법
+
+### JToast/JToaster 사용법
+
+Toast 알림은 전역적으로 메시지를 표시하는 데 사용됩니다. `JToast` 함수와 `JToaster` 컴포넌트를 함께 사용합니다.
+
+#### 설치 및 설정
+
+앱의 루트 레벨에 `<JToaster />` 컴포넌트를 추가해야 합니다:
+
+```vue
+<template>
+  <RouterView />
+  <JToaster />
+</template>
+
+<script setup>
+import { JToaster } from '@/components/atoms'
+// 또는 NPM 패키지 사용 시
+// import { JToaster } from '@j-solution/components'
+</script>
+```
+
+#### 기본 사용법
+
+```vue
+<script setup>
+import { JToast } from '@/components/atoms'
+// 또는 NPM 패키지 사용 시
+// import { JToast } from '@j-solution/components'
+
+// 기본 Toast
+const showToast = () => {
+  JToast('메시지가 표시됩니다')
+}
+
+// Success Toast
+const showSuccess = () => {
+  JToast.success('성공적으로 저장되었습니다')
+}
+
+// Error Toast
+const showError = () => {
+  JToast.error('오류가 발생했습니다')
+}
+
+// Info Toast
+const showInfo = () => {
+  JToast.info('정보 메시지입니다')
+}
+
+// Warning Toast
+const showWarning = () => {
+  JToast.warning('경고 메시지입니다')
+}
+</script>
+```
+
+#### 고급 사용법
+
+```vue
+<script setup>
+import { JToast } from '@/components/atoms'
+
+// Description이 있는 Toast
+const showWithDescription = () => {
+  JToast('제목', {
+    description: '추가 설명 텍스트',
+  })
+}
+
+// Action 버튼이 있는 Toast
+const showWithAction = () => {
+  JToast('제목', {
+    description: '설명 텍스트',
+    action: {
+      label: '실행 취소',
+      onClick: () => {
+        console.log('실행 취소')
+      },
+    },
+  })
+}
+
+// Promise Toast (비동기 작업 표시)
+const showPromiseToast = async () => {
+  await JToast.promise(
+    fetch('/api/data').then(res => res.json()),
+    {
+      loading: '로딩 중...',
+      success: (data) => `${data.name}이(가) 생성되었습니다`,
+      error: '오류가 발생했습니다',
+    }
+  )
+}
+</script>
+```
+
+**주요 특징:**
+- `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으로 원하는 입력 컴포넌트를 선택할 수 있습니다:
@@ -428,51 +1444,6 @@ const formSchema = {
 - `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 컴포넌트를 탭 콘텐츠로 표시하는 방법에 대한 가이드입니다.
@@ -706,6 +1677,30 @@ const handleMenuClick = (item) => {
 
 템플릿 컴포넌트는 전체 페이지 레이아웃을 구성하는 데 사용됩니다. 프로젝트의 요구사항에 따라 적절한 템플릿을 선택하세요.
 
+### JLayout - 기본 레이아웃
+
+커스텀 레이아웃을 구성할 때 사용합니다.
+
+```vue
+<template>
+  <JLayout>
+    <template #header>
+      <JHeader :menu-items="menuItems" />
+    </template>
+    <template #sidebar>
+      <JSidebarSimple :menu-items="menuItems" />
+    </template>
+    <template #content>
+      <RouterView />
+    </template>
+  </JLayout>
+</template>
+
+<script setup>
+import { JLayout, JHeader, JSidebarSimple } from '@/components'
+</script>
+```
+
 ### JLayoutAdvanced 사용 시
 
 - 탭 기반 멀티 페이지 애플리케이션
@@ -714,15 +1709,21 @@ const handleMenuClick = (item) => {
 - 권한 관리 필요
 
 ```vue
-<JLayoutAdvanced 
-  :menu-items="menuItems"
-  :favorites="favorites"
-  :permissions="permissions"
->
-  <template #content-tab-{id}>
-    <RouterView />
-  </template>
-</JLayoutAdvanced>
+<template>
+  <JLayoutAdvanced 
+    :menu-items="menuItems"
+    :favorites="favorites"
+    :permissions="permissions"
+  >
+    <template #content-tab-{id}>
+      <RouterView />
+    </template>
+  </JLayoutAdvanced>
+</template>
+
+<script setup>
+import { JLayoutAdvanced } from '@/components'
+</script>
 ```
 
 ### JLayoutSimple 사용 시
@@ -732,17 +1733,23 @@ const handleMenuClick = (item) => {
 - 검색 기능만 필요
 
 ```vue
-<JLayoutSimple :menu-items="menuItems">
-  <template #content>
-    <YourPageContent />
-  </template>
-</JLayoutSimple>
+<template>
+  <JLayoutSimple :menu-items="menuItems">
+    <template #content>
+      <YourPageContent />
+    </template>
+  </JLayoutSimple>
+</template>
+
+<script setup>
+import { JLayoutSimple } from '@/components'
+</script>
 ```
 
 > 💡 **레이아웃 컴포넌트 상세 정보**: [LAYOUT_TEMPLATE_GUIDE.md](./LAYOUT_TEMPLATE_GUIDE.md)를 참고하세요.
 
 ---
 
-**문서 버전**: v1.0.1  
+**문서 버전**: v1.2.0  
 **최종 업데이트**: 2025년 12월