@j-solution/components

v1.1.1

Published

6 days ago

Vue 3 Atomic Design component kit for enterprise dashboards

Downloads

397

0High
0Medium
0Low

zoshs

vue3 components atomic-design shadcn tailwindcss jwms enterprise-ui

J-Component

Vue.js 3 기반 Atomic Design 패턴 컴포넌트 라이브러리

📋 프로젝트 개요

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)

전체 릴리즈 노트 보기

🛠️ 기술 스택

핵심 프레임워크

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/                    # 빌드 결과물

🚀 시작하기

설치

# 저장소 클론
git clone <repository-url>
cd J-Component

# 의존성 설치
cd jwms-portal-frontend
npm install
# 또는
pnpm install

개발 서버 실행

# 개발 서버 시작 (http://localhost:5173)
npm run dev

Storybook 실행

# Storybook 시작 (http://localhost:6006)
npm run storybook

Storybook 기능:

다양한 폼 레이아웃/스키마(검색, 개인정보, 섹션, Wizard 등)와 Args/Docs 자동 문서 예시 확인 가능
툴바에서 테마 선택 (Default, Slate, Rose, Blue, Green)
다크모드 토글로 라이트/다크 모드 전환

빌드

# 프로덕션 빌드
npm run build

# 빌드 결과 미리보기
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 조합)

📖 사용 예시

💡 컴포넌트 사용 가이드: 사용 가이드에서 JDynamicTabs 경로 기반 컴포넌트 로딩 방법 등 상세 가이드를 확인하세요.

NPM 패키지 사용 (권장)

<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>

<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>

💡 참고: NPM 패키지는 패키지 진입점에서 CSS가 자동으로 import되므로, 컴포넌트만 import하면 스타일이 자동으로 적용됩니다.

Standard 방식 사용 (파일 복사)

<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>

<script setup>
import { ref } from 'vue'
import { JButton, JFormField, JInput, JAlert } from '@/components'

const name = ref('')

const handleClick = () => {
  console.log('버튼 클릭됨')
}
</script>

주소 검색 컴포넌트

<template>
  <JSearchAddr 
    v-model="address" 
    @select="handleAddressSelect"
    placeholder="주소를 검색하세요"
  />
</template>

<script setup>
import { ref } from 'vue'
import { JSearchAddr } from '@/components/molecules'

const address = ref('')

const handleAddressSelect = (selectedAddress) => {
  console.log('선택된 주소:', selectedAddress)
}
</script>

📚 문서 가이드

모든 문서는 이 README.md를 기준으로 연결되어 있습니다.

📖 주요 문서

| 문서 | 설명 | 대상 | |------|------|------| | 설치 가이드 | 처음 설치하는 방법 | Standard 방식, NPM 방식 설치 가이드 | | 업데이트 가이드 | 버전 업데이트 방법 | Standard 방식, NPM 방식 업데이트 가이드 | | 사용 가이드 | 컴포넌트 사용 방법 | 컴포넌트 목록, 사용 예시, 권장사항 | | 릴리즈 노트 | 버전별 변경사항 | 모든 버전의 변경 이력 |

📦 패키지 문서

패키지에 포함된 문서들 (원본: 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에서 복사)

📦 컴포넌트 패키징 및 배포

⚠️ 중요: 패키지를 생성하거나 버전을 업데이트하기 전에 반드시 다음 문서를 참조하세요:
상세 가이드: jwms-portal-frontend/PACKAGING.md
빠른 참조: PACKAGING_GUIDE.md

J-Component는 두 가지 배포 방식을 지원합니다:

🚀 통합 패키징 (권장)

하나의 명령어로 두 가지 방식 모두 생성:

cd jwms-portal-frontend
npm run package

이 명령어는 다음을 자동으로 실행합니다:

Standard 방식: packages/v{version}/ 디렉토리에 파일 복사 방식 패키지 생성
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 패키지 배포

# 로컬에서 빌드 및 배포
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 방식으로 대체됨

개별 패키징

필요한 경우 개별로 실행할 수 있습니다:

# Standard 방식만
npm run package:standard

# NPM 방식만
npm run package:npm

자세한 내용: PACKAGING.md

💡 설치 및 업데이트 방법: 설치 가이드 및 업데이트 가이드를 참고하세요.

패키지 다운로드

패키지 폴더만 다운로드하는 방법 (전체 리포지토리 클론 불필요):

⭐ 추천: Git Sparse Checkout (패키지 폴더만 다운로드):

# 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 [email protected]:<username>/<repository>.git
cd J-Component
git sparse-checkout set packages/v1.0.0

다른 방법들:

GitHub 웹 인터페이스에서 특정 디렉토리 ZIP 다운로드
GitHub API 사용
Git Submodule 사용

📝 참고: 각 패키지의 README.md에 상세한 다운로드 방법이 안내되어 있습니다.

🔧 개발 가이드

컴포넌트 작성 규칙

Atomic Design 패턴 준수
TypeScript 타입 정의 필수
Props 인터페이스 정의
Storybook 스토리 작성
Tailwind CSS 스타일링

컴포넌트 템플릿

<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
})

const emit = defineEmits<Emits>()
</script>