@j-solution/components 1.0.1 → 1.1.0

package/README.md

@@ -1,130 +1,419 @@
-# @j-solution/components
+# J-Component
 
-Vue 3 기반 Atomic Design 컴포넌트 라이브러리 **J-Component v1.0.1** 의 NPM 패키지입니다.
+> Vue.js 3 기반 Atomic Design 패턴 컴포넌트 라이브러리
 
-> 💡 **별칭 사용**: `@j/components`로 사용하려면 프로젝트에서 별칭을 설정하세요. 자세한 내용은 [별칭 설정](#별칭-설정-선택사항) 섹션을 참고하세요.
+## 📋 프로젝트 개요
 
-## 📦 설치
+J-Component는 Vue.js 3와 TypeScript를 기반으로 한 재사용 가능한 UI 컴포넌트 라이브러리입니다. shadcn/ui 디자인 시스템과 Atomic Design 패턴을 적용하여 일관성 있고 확장 가능한 컴포넌트를 제공합니다.
+
+## 🚀 현재 버전: v1.1.0
+
+**최신 업데이트 (2025년 12월 22일)**
+- **통합 패키징 지원**: `npm run package` 명령으로 Standard 방식과 NPM 방식 모두 생성
+  - Standard 방식: `packages/v{version}/` 디렉토리에 파일 복사 방식 패키지
+  - NPM 방식: `dist/npm/` 디렉토리에 `@j-solution/components` npm 패키지
+  - ES Module + CommonJS + TypeScript 타입 정의 포함
+  - 가상 모듈 자동 인라인 처리로 경로 문제 해결
+- **버전 1.0.0 릴리즈**: 첫 번째 메이저 버전
+  - v1.0.0부터는 namespaced 버전 지원 중단 (standard, npm 방식만 지원)
+  - 문서 구조 재정리 및 통합 완료 (INSTALLATION_GUIDE, UPDATE_GUIDE, USAGE_GUIDE)
+
+[전체 릴리즈 노트 보기](./RELEASE_NOTES.md)
+
+## 🛠️ 기술 스택
+
+### 핵심 프레임워크
+- **Vue.js 3.5** - 프론트엔드 프레임워크
+- **TypeScript 5.9** - 타입 시스템
+- **Vite 7** - 빌드 도구
+
+### UI & 스타일링
+- **TailwindCSS 3.4** - 유틸리티 CSS 프레임워크
+- **shadcn/ui** - 디자인 시스템 (radix-vue 기반)
+- **Lucide Icons** - 아이콘 라이브러리
+
+### 개발 도구
+- **Storybook 9** - 컴포넌트 문서화 및 테스트
+  - Docs 탭: 다양한 폼 스키마/도메인 예시 자동 미리보기 지원
+  - 테마 셀렉터: 5가지 tweakcn 테마 지원 (Default, Slate, Rose, Blue, Green)
+  - 다크모드 토글: 라이트/다크 모드 실시간 전환
+- **ESLint 9** - 코드 품질 검사
+- **Prettier** - 코드 포맷팅
+
+## 📁 프로젝트 구조
+
+```
+jwms-portal-frontend/
+├── src/
+│   ├── components/          # Atomic Design Components
+│   │   ├── atoms/           # 기본 UI 요소 (JButton, JInput, JIcon 등)
+│   │   ├── molecules/       # atoms의 조합 (JFormField, JCard, JAlert 등)
+│   │   ├── organisms/       # molecules의 조합 (JModal, JDynamicTabs, JDynamicForm 등)
+│   │   ├── shadcn/          # shadcn 컴포넌트 래핑
+│   │   └── templates/       # 페이지 레이아웃
+│   ├── stories/             # Storybook 스토리
+│   ├── types/               # TypeScript 타입 정의
+│   ├── composables/         # Vue Composition Functions
+│   └── services/            # API 서비스
+├── docs/                    # 컴포넌트 사용 가이드
+└── dist/                    # 빌드 결과물
+```
+
+## 🚀 시작하기
+
+### 설치
 
 ```bash
-npm install @j-solution/components
-# 또는
-pnpm add @j-solution/components
+# 저장소 클론
+git clone <repository-url>
+cd J-Component
+
+# 의존성 설치
+cd jwms-portal-frontend
+npm install
 # 또는
-yarn add @j-solution/components
+pnpm install
 ```
 
-### JGrid 컴포넌트 사용 시 (선택사항)
+### 개발 서버 실행
 
-JGrid 컴포넌트의 Enterprise 기능(그룹핑, 피벗, Excel 내보내기)을 사용하려면 AG Grid Enterprise를 별도로 설치해야 합니다:
+```bash
+# 개발 서버 시작 (http://localhost:5173)
+npm run dev
+```
+
+### Storybook 실행
 
 ```bash
-npm install ag-grid-enterprise
-# 또는
-pnpm add ag-grid-enterprise
+# Storybook 시작 (http://localhost:6006)
+npm run storybook
 ```
 
-> **주의**: AG Grid Enterprise는 별도의 라이선스가 필요합니다. 라이선스가 없는 경우 Community 버전만 사용 가능합니다.
+**Storybook 기능:**
+- 다양한 폼 레이아웃/스키마(검색, 개인정보, 섹션, Wizard 등)와 Args/Docs 자동 문서 예시 확인 가능
+- 툴바에서 테마 선택 (Default, Slate, Rose, Blue, Green)
+- 다크모드 토글로 라이트/다크 모드 전환
+
+### 빌드
 
-## 🚀 사용 예시
+```bash
+# 프로덕션 빌드
+npm run build
 
-```ts
-import { JButton } from '@j-solution/components'
-// CSS는 자동으로 포함됩니다 (별도 import 불필요)
+# 빌드 결과 미리보기
+npm run preview
+```
 
+## 📚 주요 컴포넌트
+
+### Atoms (기본 요소)
+- **JButton** - 버튼 컴포넌트
+- **JInput** - 입력 필드
+- **JIcon** - 아이콘 컴포넌트
+- **JLabel** - 라벨 컴포넌트
+- **JBadge** - 배지 컴포넌트
+- **JProgress** - 진행률 표시
+- **JSpinner** - 로딩 스피너
+- **JGrid** - AG Grid 기반 데이터 그리드 컴포넌트 (Enterprise 기능 지원: 그룹핑, 피벗, Excel 내보내기)
+
+### Molecules (조합 요소)
+- **JFormField** - 폼 필드 래퍼
+- **JCard** - 카드 컴포넌트
+- **JAlert** - 알림 컴포넌트
+- **JAccordion** - 아코디언 컴포넌트
+- **JContextMenu** - 컨텍스트 메뉴
+- **JSearchAddr** - 주소 검색 컴포넌트
+- **JTabs** - 탭 컴포넌트 (탭 전환 이벤트 처리 개선, component 속성 활용 지원)
+- **JButtonGroup** - 버튼 그룹 컴포넌트 (구분선 자동 표시 지원)
+- **JTitlebar** - 타이틀바 컴포넌트 (제목, 설명, 팝오버 기능)
+
+### Organisms (복합 요소)
+- **JModal** - 모달 컴포넌트 (size prop 지원: sm, md, lg, xl, 2xl, full)
+- **JDynamicTabs** - 동적 탭 관리
+- **JDynamicForm** - 스키마 기반 동적 폼(기본/섹션/다단계, Docs 탭/다양한 예시 참조)
+- **JFormModal** - JDynamicForm 기반 동적 폼 모달 컴포넌트 (size prop 지원)
+- **JSearchPanel** - JDynamicForm 기반 재사용 가능한 검색 패널 (Collapsible, 조건 요약, 초기화 기능 지원)
+- **JSidebarAdvanced** - 고급 사이드바 (검색, 즐겨찾기, 다단계 메뉴 지원)
+- **JSidebarSimple** - 간단한 사이드바 (다단계 메뉴, 검색 지원)
+
+### Templates (레이아웃)
+- **JLayoutAdvanced** - 고급 레이아웃 (JHeader + JSidebarAdvanced + JDynamicTabs 조합)
+- **JLayoutSimple** - 간단한 레이아웃 (JHeader + JSidebarSimple + JPageContainer 조합)
+
+## 📖 사용 예시
+
+> 💡 **컴포넌트 사용 가이드**: [사용 가이드](./docs/USAGE_GUIDE.md)에서 JDynamicTabs 경로 기반 컴포넌트 로딩 방법 등 상세 가이드를 확인하세요.
+
+### NPM 패키지 사용 (권장)
+
+```vue
 <template>
-  <JButton variant="primary">저장</JButton>
+  <div class="p-4">
+    <JButton variant="primary" @click="handleClick">
+      클릭하세요
+    </JButton>
+    
+    <JFormField label="이름" required>
+      <JInput v-model="name" placeholder="이름을 입력하세요" />
+    </JFormField>
+    
+    <JAlert type="info" title="알림">
+      이것은 정보 알림입니다.
+    </JAlert>
+  </div>
 </template>
+
+<script setup>
+import { ref } from 'vue'
+import { JButton, JFormField, JInput, JAlert } from '@j-solution/components'
+// CSS는 자동으로 포함됩니다 - 별도 import 불필요
+
+const name = ref('')
+
+const handleClick = () => {
+  console.log('버튼 클릭됨')
+}
+</script>
 ```
 
-> 💡 **참고**: 패키지 진입점에서 CSS가 자동으로 import되므로, 컴포넌트만 import하면 스타일이 자동으로 적용됩니다.
+> 💡 **참고**: NPM 패키지는 패키지 진입점에서 CSS가 자동으로 import되므로, 컴포넌트만 import하면 스타일이 자동으로 적용됩니다.
 
-> ⚠️ **주의**: 일부 번들러 설정에서는 CSS가 자동으로 포함되지 않을 수 있습니다. 그 경우 다음처럼 수동으로 import하세요:
-> 
-> ```ts
-> import '@j-solution/components/assets/styles/j-components.css'
-> import '@j-solution/components/assets/styles/themes.css'
-> ```
+### Standard 방식 사용 (파일 복사)
 
-### Tailwind 설정
+```vue
+<template>
+  <div class="p-4">
+    <JButton variant="primary" @click="handleClick">
+      클릭하세요
+    </JButton>
+    
+    <JFormField label="이름" required>
+      <JInput v-model="name" placeholder="이름을 입력하세요" />
+    </JFormField>
+    
+    <JAlert type="info" title="알림">
+      이것은 정보 알림입니다.
+    </JAlert>
+  </div>
+</template>
 
-`tailwind.config.js` 의 `content` 항목에 다음을 추가합니다:
+<script setup>
+import { ref } from 'vue'
+import { JButton, JFormField, JInput, JAlert } from '@/components'
 
-```js
-export default {
-  content: [
-    "./index.html",
-    "./src/**/*.{vue,js,ts,jsx,tsx}",
-    "./node_modules/@j-solution/components/**/*.{vue,js,ts}",
-  ],
-  // ... 기타 설정
+const name = ref('')
+
+const handleClick = () => {
+  console.log('버튼 클릭됨')
 }
+</script>
 ```
 
-> 💡 **참고**: 제공되는 `tailwind.config.js` 파일을 참고하여 컬러/반지름 설정을 병합할 수 있습니다.
+### 주소 검색 컴포넌트
 
-## 📚 문서
+```vue
+<template>
+  <JSearchAddr 
+    v-model="address" 
+    @select="handleAddressSelect"
+    placeholder="주소를 검색하세요"
+  />
+</template>
 
-- USAGE_GUIDE.md: 필수 의존성과 사용 가이드
-- UPDATE_GUIDE.md: 버전 업그레이드 체크리스트
-- docs/README: https://github.com/JWMS-Solutions/J-Component
+<script setup>
+import { ref } from 'vue'
+import { JSearchAddr } from '@/components/molecules'
 
-## 🧩 서브 경로 import
+const address = ref('')
 
-```ts
-import { JButton } from '@j-solution/components'
-import { JHeader } from '@j-solution/components/components/organisms'
-import type { MenuPermission } from '@j-solution/components/types/sidebar-menu.types'
+const handleAddressSelect = (selectedAddress) => {
+  console.log('선택된 주소:', selectedAddress)
+}
+</script>
 ```
 
-## 별칭 설정 (선택사항)
+## 📚 문서 가이드
 
-`@j/components`로 사용하려면 프로젝트에서 별칭을 설정하세요:
+> **모든 문서는 이 README.md를 기준으로 연결되어 있습니다.**
 
-### Vite 프로젝트
+### 📖 주요 문서
 
-`vite.config.ts`에 별칭 추가:
+| 문서 | 설명 | 대상 |
+|------|------|------|
+| **[설치 가이드](./docs/INSTALLATION_GUIDE.md)** | 처음 설치하는 방법 | Standard 방식, NPM 방식 설치 가이드 |
+| **[업데이트 가이드](./docs/UPDATE_GUIDE.md)** | 버전 업데이트 방법 | Standard 방식, NPM 방식 업데이트 가이드 |
+| **[사용 가이드](./docs/USAGE_GUIDE.md)** | 컴포넌트 사용 방법 | 컴포넌트 목록, 사용 예시, 권장사항 |
+| **[릴리즈 노트](./RELEASE_NOTES.md)** | 버전별 변경사항 | 모든 버전의 변경 이력 |
 
-```ts
-import path from 'path'
-import { defineConfig } from 'vite'
+### 📦 패키지 문서
 
-export default defineConfig({
-  resolve: {
-    alias: {
-      '@j/components': path.resolve(__dirname, './node_modules/@j-solution/components'),
-      '@j': path.resolve(__dirname, './node_modules/@j-solution/components'),
-    }
-  }
-})
+패키지에 포함된 문서들 (원본: `docs/` 디렉토리):
+
+- **`packages/v{version}/README.md`**: 패키지 소개 및 설치 방법
+- **`packages/v{version}/USAGE_GUIDE.md`**: 컴포넌트 사용 가이드
+- **`packages/v{version}/UPDATE_GUIDE.md`**: 버전 업데이트 가이드
+
+> 💡 **참고**: 패키지 문서는 `docs/` 디렉토리의 원본을 기반으로 패키징 시 자동으로 포함됩니다.
+
+### 🗺️ 문서 구조
+
+```
+J-Component/
+├── README.md                    # 메인 문서 (이 파일)
+├── RELEASE_NOTES.md             # 릴리즈 노트
+├── docs/                        # 문서 원본
+│   ├── INSTALLATION_GUIDE.md    # 설치 가이드
+│   ├── UPDATE_GUIDE.md          # 업데이트 가이드
+│   └── USAGE_GUIDE.md           # 사용 가이드
+└── packages/                    # 배포 패키지
+    └── v{version}/
+        ├── README.md            # (docs에서 복사)
+        ├── USAGE_GUIDE.md      # (docs에서 복사)
+        └── UPDATE_GUIDE.md     # (docs에서 복사)
 ```
 
-### TypeScript 프로젝트
+---
 
-`tsconfig.json`에 paths 추가:
+## 📦 컴포넌트 패키징 및 배포
 
-```json
-{
-  "compilerOptions": {
-    "paths": {
-      "@j/components/*": ["./node_modules/@j-solution/components/*"],
-      "@j/*": ["./node_modules/@j-solution/components/*"]
-    }
-  }
-}
+> **⚠️ 중요**: 패키지를 생성하거나 버전을 업데이트하기 전에 **반드시** 다음 문서를 참조하세요:
+> - **상세 가이드**: [`jwms-portal-frontend/PACKAGING.md`](./jwms-portal-frontend/PACKAGING.md)
+> - **빠른 참조**: [`PACKAGING_GUIDE.md`](./PACKAGING_GUIDE.md)
+
+J-Component는 **두 가지 배포 방식**을 지원합니다:
+
+### 🚀 통합 패키징 (권장)
+
+**하나의 명령어로 두 가지 방식 모두 생성:**
+
+```bash
+cd jwms-portal-frontend
+npm run package
+```
+
+이 명령어는 다음을 자동으로 실행합니다:
+1. **Standard 방식**: `packages/v{version}/` 디렉토리에 파일 복사 방식 패키지 생성
+2. **NPM 방식**: `dist/npm/` 디렉토리에 npm 패키지 생성
+
+### 1) Standard 방식 (파일 복사)
+
+- **출력 위치**: `packages/v{version}/`
+- **사용 방법**: 타겟 프로젝트에 파일을 직접 복사하여 사용
+- **특징**: 
+  - 기존 프로젝트 구조와 동일
+  - Git에 커밋 가능 (버전별 스냅샷)
+  - `packages/latest/standard/`에 최신 버전 포인터 제공
+
+### 2) NPM 방식 (npm 패키지)
+
+- **출력 위치**: `dist/npm/`
+- **사용 방법**: 
+  - 로컬 테스트: `npm install file:../path/to/dist/npm`
+  - npm 레지스트리: `npm install @j-solution/components` (배포 후)
+- **특징**:
+  - ES Module + CommonJS + TypeScript 타입 정의 포함
+  - 가상 모듈 자동 인라인 처리
+  - `dist` 디렉토리는 `.gitignore`에 포함 (빌드 시 자동 생성)
+
+#### NPM 패키지 배포
+
+```bash
+# 로컬에서 빌드 및 배포
+cd jwms-portal-frontend/dist/npm
+npm publish --access public
+# 또는
+pnpm publish --access public
+```
+
+#### 자동 배포 (GitHub Actions)
+- GitHub에서 Release를 생성하면 자동으로 npm 레지스트리에 배포
+- `.github/workflows/publish-npm.yml` 워크플로우 자동 실행
+- `NPM_TOKEN` 시크릿 필요
+
+### ⚠️ 중요 사항
+
+- **v1.0.0부터 namespaced 방식 지원 중단**
+  - 기존: standard, namespaced, npm (3가지)
+  - 현재: standard, npm (2가지)
+  - namespaced 방식은 npm 방식으로 대체됨
+
+### 개별 패키징
+
+필요한 경우 개별로 실행할 수 있습니다:
+
+```bash
+# Standard 방식만
+npm run package:standard
+
+# NPM 방식만
+npm run package:npm
 ```
 
-설정 후 `@j/components`로 import 가능:
+자세한 내용: [PACKAGING.md](./jwms-portal-frontend/PACKAGING.md)
+
+> 💡 **설치 및 업데이트 방법**: [설치 가이드](./docs/INSTALLATION_GUIDE.md) 및 [업데이트 가이드](./docs/UPDATE_GUIDE.md)를 참고하세요.
+
+### 패키지 다운로드
 
-```ts
-import { JButton } from '@j/components'  // ✅ 별칭 사용
-// CSS는 자동으로 포함됩니다 (별도 import 불필요)
+패키지 폴더만 다운로드하는 방법 (전체 리포지토리 클론 불필요):
+
+**⭐ 추천: Git Sparse Checkout** (패키지 폴더만 다운로드):
+```bash
+# Public 리포지토리
+git clone --depth 1 --filter=blob:none --sparse <repository-url>
+cd J-Component
+git sparse-checkout set packages/v1.0.0
+# 또는 packages/latest/standard
+
+# Private 리포지토리 (인증 필요)
+git clone --depth 1 --filter=blob:none --sparse git@github.com:<username>/<repository>.git
+cd J-Component
+git sparse-checkout set packages/v1.0.0
 ```
 
-## 📤 배포
+**다른 방법들**:
+- GitHub 웹 인터페이스에서 특정 디렉토리 ZIP 다운로드
+- GitHub API 사용
+- Git Submodule 사용
+
+> **📝 참고**: 각 패키지의 `README.md`에 상세한 다운로드 방법이 안내되어 있습니다.
+
+## 🔧 개발 가이드
+
+### 컴포넌트 작성 규칙
 
-1. `npm run package:npm` (또는 `pnpm run package:npm`)
-2. `cd dist/npm`
-3. `npm publish --access public` (또는 `pnpm publish --access public`)
+1. **Atomic Design 패턴** 준수
+2. **TypeScript** 타입 정의 필수
+3. **Props** 인터페이스 정의
+4. **Storybook** 스토리 작성
+5. **Tailwind CSS** 스타일링
+
+### 컴포넌트 템플릿
+
+```vue
+<template>
+  <div class="j-component">
+    <!-- 컴포넌트 내용 -->
+  </div>
+</template>
+
+<script setup lang="ts">
+interface Props {
+  variant?: 'primary' | 'secondary'
+  size?: 'sm' | 'md' | 'lg'
+  disabled?: boolean
+}
+
+interface Emits {
+  (e: 'click', value: string): void
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  variant: 'primary',
+  size: 'md',
+  disabled: false
+})
 
-추가 가이드는 `USAGE_GUIDE.md` 와 `UPDATE_GUIDE.md` 를 참고하세요.
+const emit = defineEmits<Emits>()
+</script>
+```