Vue 3 Atomic Design component kit for enterprise dashboards
npm install @j-solution/componentsenableTreeData, getDataPath)
rowClicked, cellClicked, selectionChanged 등 6종 이벤트 + v-model:selectedRows
value: '' 옵션 클릭 시 선택되지 않던 버그 수정
height prop 문자열 지원, readonly 속성 호환성 수정
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/ # 빌드 결과물
`
🚀 시작하기
$3
`bash
저장소 클론
git clone
cd J-Component
의존성 설치
cd jwms-portal-frontend
npm install
또는
pnpm install
`
$3
`bash
개발 서버 시작 (http://localhost:5173)
npm run dev
`
$3
`bash
Storybook 시작 (http://localhost:6006)
npm run storybook
`
Storybook 기능:
- 다양한 폼 레이아웃/스키마(검색, 개인정보, 섹션, Wizard 등)와 Args/Docs 자동 문서 예시 확인 가능
- 툴바에서 테마 선택 (Default, Slate, Rose, Blue, Green)
- 다크모드 토글로 라이트/다크 모드 전환
$3
`bash
프로덕션 빌드
npm run build
빌드 결과 미리보기
npm run preview
`
📚 주요 컴포넌트
$3
- JButton - 버튼 컴포넌트
- JInput - 입력 필드
- JIcon - 아이콘 컴포넌트
- JLabel - 라벨 컴포넌트
- JBadge - 배지 컴포넌트
- JProgress - 진행률 표시
- JSpinner - 로딩 스피너
- JGrid - AG Grid 기반 데이터 그리드 컴포넌트 (Enterprise 기능 지원: 그룹핑, 피벗, Excel 내보내기)
$3
- JFormField - 폼 필드 래퍼
- JCard - 카드 컴포넌트
- JAlert - 알림 컴포넌트
- JAccordion - 아코디언 컴포넌트
- JContextMenu - 컨텍스트 메뉴
- JSearchAddr - 주소 검색 컴포넌트
- JTabs - 탭 컴포넌트 (탭 전환 이벤트 처리 개선, component 속성 활용 지원)
- JButtonGroup - 버튼 그룹 컴포넌트 (구분선 자동 표시 지원)
- JTitlebar - 타이틀바 컴포넌트 (제목, 설명, 팝오버 기능)
$3
- JModal - 모달 컴포넌트 (size prop 지원: sm, md, lg, xl, 2xl, full)
- JDynamicTabs - 동적 탭 관리
- JDynamicForm - 스키마 기반 동적 폼(기본/섹션/다단계, Docs 탭/다양한 예시 참조)
- JFormModal - JDynamicForm 기반 동적 폼 모달 컴포넌트 (size prop 지원)
- JSearchPanel - JDynamicForm 기반 재사용 가능한 검색 패널 (Collapsible, 조건 요약, 초기화 기능 지원)
- JSidebarAdvanced - 고급 사이드바 (검색, 즐겨찾기, 다단계 메뉴 지원)
- JSidebarSimple - 간단한 사이드바 (다단계 메뉴, 검색 지원)
$3
- JLayoutAdvanced - 고급 레이아웃 (JHeader + JSidebarAdvanced + JDynamicTabs 조합)
- JLayoutSimple - 간단한 레이아웃 (JHeader + JSidebarSimple + JPageContainer 조합)
📖 사용 예시
> 💡 컴포넌트 사용 가이드: 사용 가이드에서 JDynamicTabs 경로 기반 컴포넌트 로딩 방법 등 상세 가이드를 확인하세요.
$3
`vue
클릭하세요
이것은 정보 알림입니다.
`
> 💡 참고: NPM 패키지는 패키지 진입점에서 CSS가 자동으로 import되므로, 컴포넌트만 import하면 스타일이 자동으로 적용됩니다.
$3
`vue
클릭하세요
이것은 정보 알림입니다.
`
$3
`vue
@select="handleAddressSelect"
placeholder="주소를 검색하세요"
/>
`
📚 문서 가이드
> 모든 문서는 이 README.md를 기준으로 연결되어 있습니다.
$3
| 문서 | 설명 | 대상 |
|------|------|------|
| 설치 가이드 | 처음 설치하는 방법 | Standard 방식, NPM 방식 설치 가이드 |
| 업데이트 가이드 | 버전 업데이트 방법 | Standard 방식, NPM 방식 업데이트 가이드 |
| 사용 가이드 | 컴포넌트 사용 방법 | 컴포넌트 목록, 사용 예시, 권장사항 |
| 릴리즈 노트 | 버전별 변경사항 | 모든 버전의 변경 이력 |
$3
패키지에 포함된 문서들 (원본: docs/ 디렉토리):
- packages/v{version}/README.md: 패키지 소개 및 설치 방법
- packages/v{version}/USAGE_GUIDE.md: 컴포넌트 사용 가이드
- packages/v{version}/UPDATE_GUIDE.md: 버전 업데이트 가이드
> 💡 참고: 패키지 문서는 docs/ 디렉토리의 원본을 기반으로 패키징 시 자동으로 포함됩니다.
$3
`
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에서 복사)
`
---
📦 컴포넌트 패키징 및 배포
> ⚠️ 중요: 패키지를 생성하거나 버전을 업데이트하기 전에 반드시 다음 문서를 참조하세요:
> - 상세 가이드: jwms-portal-frontend/PACKAGING.md
> - 빠른 참조: PACKAGING_GUIDE.md
J-Component는 두 가지 배포 방식을 지원합니다:
$3
하나의 명령어로 두 가지 방식 모두 생성:
`bash
cd jwms-portal-frontend
npm run package
`
이 명령어는 다음을 자동으로 실행합니다:
1. Standard 방식: packages/v{version}/ 디렉토리에 파일 복사 방식 패키지 생성
2. NPM 방식: dist/npm/ 디렉토리에 npm 패키지 생성
$3
- 출력 위치: packages/v{version}/
- 사용 방법: 타겟 프로젝트에 파일을 직접 복사하여 사용
- 특징:
- 기존 프로젝트 구조와 동일
- Git에 커밋 가능 (버전별 스냅샷)
- packages/latest/standard/에 최신 버전 포인터 제공
$3
- 출력 위치: 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 시크릿 필요
$3
- v1.0.0부터 namespaced 방식 지원 중단
- 기존: standard, namespaced, npm (3가지)
- 현재: standard, npm (2가지)
- namespaced 방식은 npm 방식으로 대체됨
$3
필요한 경우 개별로 실행할 수 있습니다:
`bash
Standard 방식만
npm run package:standard
NPM 방식만
npm run package:npm
`
자세한 내용: PACKAGING.md
> 💡 설치 및 업데이트 방법: 설치 가이드 및 업데이트 가이드를 참고하세요.
$3
패키지 폴더만 다운로드하는 방법 (전체 리포지토리 클론 불필요):
⭐ 추천: Git Sparse Checkout (패키지 폴더만 다운로드):
`bash
Public 리포지토리
git clone --depth 1 --filter=blob:none --sparse
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:/.git
cd J-Component
git sparse-checkout set packages/v1.0.0
`
다른 방법들:
- GitHub 웹 인터페이스에서 특정 디렉토리 ZIP 다운로드
- GitHub API 사용
- Git Submodule 사용
> 📝 참고: 각 패키지의 README.md에 상세한 다운로드 방법이 안내되어 있습니다.
🔧 개발 가이드
$3
1. Atomic Design 패턴 준수
2. TypeScript 타입 정의 필수
3. Props 인터페이스 정의
4. Storybook 스토리 작성
5. Tailwind CSS 스타일링
$3
`vue
``