@j-solution/components

J-Component

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

📋 프로젝트 개요

J-Component는 Vue.js 3와 TypeScript를 기반으로 한 재사용 가능한 UI 컴포넌트 라이브러리입니다. shadcn/ui 디자인 시스템과 Atomic Design 패턴을 적용하여 일관성 있고 확장 가능한 컴포넌트를 제공합니다.

🚀 현재 버전: v2.1.3

최신 업데이트 (2026년 5월 7일)

• JFormField description 슬롯 추가: 라벨 우측 info 아이콘 hover 팝오버 본문에 description named slot을 신규 노출 — 단순 문자열을 넘어 <strong>/<code>/줄바꿈/컴포넌트 등 자유로운 마크업으로 도움말을 구성할 수 있으며, 슬롯 미지정 시 기존 description prop 텍스트를 그대로 출력해 v2.1.2 사용처와 호환됩니다.
• JSplitter Methods 타입 정정: JSplitterMethods.isFirstCollapsed / isSecondCollapsed 타입을 boolean에서 ComputedRef<boolean>으로 정정해 defineExpose로 노출되는 실제 형태와 시그니처를 일치시켰습니다 — 외부에서 splitterRef.value.isFirstCollapsed.value 접근 시 누락되던 .value를 컴파일러가 검출합니다 (런타임 동작 변경 없음).
• tsconfig 정리: tsconfig.app.json에서 사용하지 않는 baseUrl 옵션을 제거해 paths만 사용하도록 정리했습니다 (빌드 산출물 및 외부 사용 영향 없음).

전체 릴리즈 노트 보기

🛠️ 기술 스택

핵심 프레임워크

• Vue.js 3.5 - 프론트엔드 프레임워크
• TypeScript 5.9 - 타입 시스템
• Vite 7 - 빌드 도구

UI & 스타일링

• TailwindCSS 3.4 - 유틸리티 CSS 프레임워크
• shadcn/ui - 디자인 시스템 (radix-vue 기반)
• Lucide Icons - 아이콘 라이브러리

개발 도구

• Storybook 9 - 컴포넌트 문서화 및 테스트
  • Docs 탭: 다양한 폼 스키마/도메인 예시 자동 미리보기 지원
  • 테마 셀렉터: 8가지 tweakcn 테마 지원 (Default, Slate, Rose, Blue, Green, Purple, Orange, Vescrow)
  • 다크모드 토글: 라이트/다크 모드 실시간 전환
• 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를 기준으로 연결되어 있습니다.

📖 주요 문서

📦 패키지 문서

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

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

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 패키지 배포

# 로컬에서 빌드 및 배포
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 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. Atomic Design 패턴 준수
2. TypeScript 타입 정의 필수
3. Props 인터페이스 정의
4. Storybook 스토리 작성
5. 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>