@bigtablet/design-system 1.18.0 → 1.18.2

package/README.md

@@ -6,6 +6,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@bigtablet/design-system.svg)](https://www.npmjs.com/package/@bigtablet/design-system)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Test Coverage](https://img.shields.io/badge/coverage-86%25-brightgreen.svg)](https://github.com/Bigtablet/bigtablet-design-system/actions)
 
 Bigtablet의 공식 디자인 시스템으로, Foundation(디자인 토큰)과 Components(UI 컴포넌트)로 구성된 통합 UI 라이브러리입니다.
 
@@ -15,19 +16,6 @@ Bigtablet의 공식 디자인 시스템으로, Foundation(디자인 토큰)과 C
 
 ---
 
-## 목차
-
-- [주요 특징](#주요-특징)
-- [설치](#설치)
-- [빠른 시작](#빠른-시작)
-- [Vanilla JS (HTML/CSS/JS)](#vanilla-js-htmlcssjs)
-- [컴포넌트](#컴포넌트)
-- [Foundation (디자인 토큰)](#foundation-디자인-토큰)
-- [개발 가이드](#개발-가이드)
-- [기여하기](#기여하기)
-
----
-
 ## 주요 특징
 
 - **React 19 지원** - 최신 React 버전 완벽 지원
@@ -36,7 +24,7 @@ Bigtablet의 공식 디자인 시스템으로, Foundation(디자인 토큰)과 C
 - **Vanilla JS** - Thymeleaf, JSP 등 서버 템플릿 지원
 - **디자인 토큰** - 일관된 색상, 타이포그래피, 간격 시스템
 - **접근성(a11y)** - 키보드 네비게이션, 스크린 리더 호환
-- **Storybook** - 인터랙티브 문서화
+- **86% 테스트 커버리지** - 안정적인 컴포넌트 품질
 
 ---
 
@@ -88,655 +76,61 @@ import '@bigtablet/design-system/style.css';
 export default function Layout({ children }) {
   return (
     <div>
-      <Sidebar
-        items={[
-          { label: '홈', href: '/' },
-          { label: '대시보드', href: '/dashboard' }
-        ]}
-      />
+      <Sidebar items={[{ label: '홈', href: '/' }]} />
       <main>{children}</main>
     </div>
   );
 }
 ```
 
----
-
-## Vanilla JS (HTML/CSS/JS)
-
-React 없이 **Thymeleaf, JSP, PHP** 등 서버 템플릿 환경에서 사용할 수 있습니다.
+### Vanilla JS (HTML/CSS/JS)
 
 ```html
-<!-- CSS -->
 <link rel="stylesheet" href="https://unpkg.com/@bigtablet/design-system/dist/vanilla/bigtablet.min.css">
-
-<!-- JS (선택) -->
 <script src="https://unpkg.com/@bigtablet/design-system/dist/vanilla/bigtablet.min.js"></script>
-```
 
-```html
 <button class="bt-button bt-button--md bt-button--primary">버튼</button>
-
-<div class="bt-text-field">
-  <label class="bt-text-field__label">이메일</label>
-  <div class="bt-text-field__wrap">
-    <input type="text" class="bt-text-field__input bt-text-field__input--outline bt-text-field__input--md">
-  </div>
-</div>
 ```
 
-👉 **[Vanilla JS 전체 문서 보기](./docs/VANILLA.md)**
-
 ---
 
 ## 컴포넌트
 
-### General
-
-#### Button
-
-```tsx
-import { Button } from '@bigtablet/design-system';
-
-// 기본 사용
-<Button>클릭</Button>
-
-// Variants
-<Button variant="primary">Primary</Button>
-<Button variant="secondary">Secondary</Button>
-<Button variant="ghost">Ghost</Button>
-<Button variant="danger">Danger</Button>
-
-// Sizes
-<Button size="sm">Small</Button>
-<Button size="md">Medium</Button>
-<Button size="lg">Large</Button>
-
-// 너비 조절
-<Button width="200px">고정 너비</Button>
-<Button width="100%">전체 너비</Button>
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'danger'` | `'primary'` | 버튼 스타일 |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 버튼 크기 |
-| `width` | `string` | `'100%'` | 버튼 너비 |
-| `disabled` | `boolean` | `false` | 비활성화 |
-
-#### Select
-
-```tsx
-import { Select } from '@bigtablet/design-system';
-
-const options = [
-  { value: 'apple', label: '사과' },
-  { value: 'banana', label: '바나나' },
-  { value: 'orange', label: '오렌지', disabled: true },
-];
-
-// 기본 사용
-<Select
-  label="과일 선택"
-  options={options}
-  placeholder="선택하세요"
-  onChange={(value, option) => console.log(value, option)}
-/>
-
-// Controlled
-const [fruit, setFruit] = useState<string | null>(null);
-<Select
-  options={options}
-  value={fruit}
-  onChange={(value) => setFruit(value)}
-/>
-
-// Variants & Sizes
-<Select options={options} variant="outline" size="md" />
-<Select options={options} variant="filled" size="lg" />
-<Select options={options} variant="ghost" size="sm" />
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `options` | `SelectOption[]` | required | 옵션 목록 |
-| `value` | `string \| null` | - | 선택된 값 (controlled) |
-| `defaultValue` | `string \| null` | `null` | 기본 선택값 |
-| `onChange` | `(value, option) => void` | - | 변경 핸들러 |
-| `placeholder` | `string` | `'Select…'` | 플레이스홀더 |
-| `variant` | `'outline' \| 'filled' \| 'ghost'` | `'outline'` | 스타일 |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 크기 |
-| `fullWidth` | `boolean` | `false` | 전체 너비 |
-| `disabled` | `boolean` | `false` | 비활성화 |
-
----
-
-### Form
-
-#### TextField
-
-```tsx
-import { TextField } from '@bigtablet/design-system';
-
-// 기본 사용
-<TextField label="이름" placeholder="이름을 입력하세요" />
-
-// 상태 표시
-<TextField label="이메일" error helperText="유효하지 않은 이메일입니다" />
-<TextField label="이메일" success helperText="사용 가능한 이메일입니다" />
-
-// 아이콘
-import { Search, Eye } from 'lucide-react';
-<TextField leftIcon={<Search size={16} />} placeholder="검색..." />
-<TextField rightIcon={<Eye size={16} />} type="password" />
-
-// Variants
-<TextField variant="outline" label="Outline" />
-<TextField variant="filled" label="Filled" />
-<TextField variant="ghost" label="Ghost" />
-
-// 값 변환 (자동 포맷팅)
-<TextField
-  label="전화번호"
-  transformValue={(v) => v.replace(/\D/g, '').slice(0, 11)}
-  onChangeAction={(value) => console.log(value)}
-/>
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `label` | `string` | - | 라벨 |
-| `helperText` | `string` | - | 도움말 텍스트 |
-| `error` | `boolean` | `false` | 에러 상태 |
-| `success` | `boolean` | `false` | 성공 상태 |
-| `variant` | `'outline' \| 'filled' \| 'ghost'` | `'outline'` | 스타일 |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 크기 |
-| `leftIcon` | `ReactNode` | - | 왼쪽 아이콘 |
-| `rightIcon` | `ReactNode` | - | 오른쪽 아이콘 |
-| `fullWidth` | `boolean` | `false` | 전체 너비 |
-| `onChangeAction` | `(value: string) => void` | - | 값 변경 콜백 |
-| `transformValue` | `(value: string) => string` | - | 값 변환 함수 |
-
-#### DatePicker
-
-```tsx
-import { DatePicker } from '@bigtablet/design-system';
-
-// 기본 사용 (연-월-일)
-const [date, setDate] = useState('');
-<DatePicker
-  label="생년월일"
-  value={date}
-  onChange={setDate}
-/>
-
-// 연-월 모드
-<DatePicker
-  label="시작 월"
-  mode="year-month"
-  value={date}
-  onChange={setDate}
-/>
-
-// 범위 제한
-<DatePicker
-  label="예약일"
-  startYear={2020}
-  endYear={2030}
-  selectableRange="until-today"  // 오늘까지만 선택 가능
-  value={date}
-  onChange={setDate}
-/>
-
-// 너비 조절
-<DatePicker label="날짜" width={300} onChange={setDate} />
-<DatePicker label="날짜" width="50%" onChange={setDate} />
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `label` | `string` | - | 라벨 |
-| `value` | `string` | - | 선택된 날짜 (`'YYYY-MM-DD'` 또는 `'YYYY-MM'`) |
-| `onChange` | `(value: string) => void` | required | 변경 핸들러 |
-| `mode` | `'year-month' \| 'year-month-day'` | `'year-month-day'` | 날짜 선택 모드 |
-| `startYear` | `number` | `1950` | 시작 연도 |
-| `endYear` | `number` | `현재년도 + 10` | 종료 연도 |
-| `selectableRange` | `'all' \| 'until-today'` | `'all'` | 선택 가능 범위 |
-| `minDate` | `string` | - | 최소 날짜 |
-| `width` | `number \| string` | `'100%'` | 너비 |
-| `disabled` | `boolean` | `false` | 비활성화 |
-
-#### Checkbox
-
-```tsx
-import { Checkbox } from '@bigtablet/design-system';
-
-// 기본 사용
-<Checkbox label="동의합니다" />
-
-// Controlled
-const [checked, setChecked] = useState(false);
-<Checkbox
-  label="알림 받기"
-  checked={checked}
-  onChange={(e) => setChecked(e.target.checked)}
-/>
-
-// Indeterminate (부분 선택)
-<Checkbox label="전체 선택" indeterminate />
-
-// Sizes
-<Checkbox size="sm" label="Small" />
-<Checkbox size="md" label="Medium" />
-<Checkbox size="lg" label="Large" />
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `label` | `ReactNode` | - | 라벨 |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 크기 |
-| `indeterminate` | `boolean` | `false` | 부분 선택 상태 |
-| `checked` | `boolean` | - | 체크 상태 |
-| `disabled` | `boolean` | `false` | 비활성화 |
-
-#### Radio
-
-```tsx
-import { Radio } from '@bigtablet/design-system';
-
-const [selected, setSelected] = useState('option1');
-
-<Radio
-  name="options"
-  value="option1"
-  label="옵션 1"
-  checked={selected === 'option1'}
-  onChange={(e) => setSelected(e.target.value)}
-/>
-<Radio
-  name="options"
-  value="option2"
-  label="옵션 2"
-  checked={selected === 'option2'}
-  onChange={(e) => setSelected(e.target.value)}
-/>
-```
-
-#### Switch
-
-```tsx
-import { Switch } from '@bigtablet/design-system';
-
-// 기본 사용
-<Switch onChange={(checked) => console.log(checked)} />
-
-// Controlled
-const [isOn, setIsOn] = useState(false);
-<Switch checked={isOn} onChange={setIsOn} />
-
-// Sizes
-<Switch size="sm" />
-<Switch size="md" />
-<Switch size="lg" />
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `checked` | `boolean` | - | 켜짐 상태 (controlled) |
-| `defaultChecked` | `boolean` | `false` | 기본 상태 |
-| `onChange` | `(checked: boolean) => void` | - | 변경 핸들러 |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 크기 |
-| `disabled` | `boolean` | `false` | 비활성화 |
-
-#### FileInput
-
-```tsx
-import { FileInput } from '@bigtablet/design-system';
-
-<FileInput
-  label="파일 선택"
-  accept="image/*"
-  onFiles={(files) => console.log(files)}
-/>
-
-// 여러 파일
-<FileInput
-  label="이미지 업로드"
-  accept="image/*"
-  multiple
-  onFiles={(files) => console.log(files)}
-/>
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `label` | `string` | `'파일 선택'` | 버튼 라벨 |
-| `accept` | `string` | - | 허용 파일 타입 |
-| `onFiles` | `(files: FileList \| null) => void` | - | 파일 선택 핸들러 |
-| `multiple` | `boolean` | `false` | 다중 선택 |
-| `disabled` | `boolean` | `false` | 비활성화 |
-
----
-
-### Feedback
-
-#### Alert
-
-```tsx
-import { AlertProvider, useAlert } from '@bigtablet/design-system';
-
-// App에 Provider 추가
-function App() {
-  return (
-    <AlertProvider>
-      <YourComponent />
-    </AlertProvider>
-  );
-}
-
-// 사용
-function YourComponent() {
-  const { showAlert } = useAlert();
-
-  const handleDelete = () => {
-    showAlert({
-      variant: 'warning',
-      title: '삭제 확인',
-      message: '정말 삭제하시겠습니까?',
-      showCancel: true,
-      confirmText: '삭제',
-      cancelText: '취소',
-      onConfirm: () => console.log('삭제됨'),
-      onCancel: () => console.log('취소됨'),
-    });
-  };
-
-  return <button onClick={handleDelete}>삭제</button>;
-}
-```
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `variant` | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` | 알림 타입 |
-| `title` | `ReactNode` | - | 제목 |
-| `message` | `ReactNode` | - | 메시지 |
-| `confirmText` | `string` | `'확인'` | 확인 버튼 텍스트 |
-| `cancelText` | `string` | `'취소'` | 취소 버튼 텍스트 |
-| `showCancel` | `boolean` | `false` | 취소 버튼 표시 |
-| `actionsAlign` | `'left' \| 'center' \| 'right'` | `'right'` | 버튼 정렬 |
-| `onConfirm` | `() => void` | - | 확인 핸들러 |
-| `onCancel` | `() => void` | - | 취소 핸들러 |
-
-#### Toast
-
-```tsx
-import { ToastProvider, useToast } from '@bigtablet/design-system';
-
-// App에 Provider 추가
-function App() {
-  return (
-    <>
-      <ToastProvider />
-      <YourComponent />
-    </>
-  );
-}
-
-// 사용
-function YourComponent() {
-  const toast = useToast();
-
-  return (
-    <div>
-      <button onClick={() => toast.success('저장되었습니다')}>성공</button>
-      <button onClick={() => toast.error('오류가 발생했습니다')}>에러</button>
-      <button onClick={() => toast.warning('주의가 필요합니다')}>경고</button>
-      <button onClick={() => toast.info('참고 정보입니다')}>정보</button>
-      <button onClick={() => toast.message('일반 메시지')}>메시지</button>
-    </div>
-  );
-}
-```
-
-#### Spinner
-
-```tsx
-import { Spinner } from '@bigtablet/design-system';
-
-<Spinner />           // 기본 (24px)
-<Spinner size={16} /> // 작은 크기
-<Spinner size={48} /> // 큰 크기
-```
-
-#### TopLoading
-
-```tsx
-import { TopLoading } from '@bigtablet/design-system';
-
-// Indeterminate (무한 로딩)
-<TopLoading isLoading />
-
-// Progress (진행률 표시)
-<TopLoading isLoading progress={65} />
-
-// 커스텀 스타일
-<TopLoading isLoading color="#ff0000" height={5} />
-
-// 숨기기
-<TopLoading isLoading={false} />
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `isLoading` | `boolean` | `true` | 표시 여부 |
-| `progress` | `number` | - | 진행률 (0-100), 없으면 indeterminate |
-| `color` | `string` | primary | 로딩바 색상 |
-| `height` | `number` | `3` | 로딩바 높이 (px) |
-
----
-
-### Navigation
-
-#### Pagination
-
-```tsx
-import { Pagination } from '@bigtablet/design-system';
-
-const [page, setPage] = useState(1);
-
-<Pagination
-  page={page}
-  totalPages={20}
-  onChange={setPage}
-/>
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `page` | `number` | required | 현재 페이지 |
-| `totalPages` | `number` | required | 전체 페이지 수 |
-| `onChange` | `(page: number) => void` | required | 페이지 변경 핸들러 |
-
-#### Sidebar (Next.js)
-
-```tsx
-import { Sidebar } from '@bigtablet/design-system/next';
-import { Home, Settings, Users } from 'lucide-react';
-
-const items = [
-  { href: '/', label: '홈', icon: Home },
-  { href: '/users', label: '사용자', icon: Users },
-  {
-    type: 'group',
-    id: 'settings',
-    label: '설정',
-    icon: Settings,
-    children: [
-      { href: '/settings/profile', label: '프로필' },
-      { href: '/settings/security', label: '보안' },
-    ],
-  },
-];
-
-<Sidebar
-  items={items}
-  activePath={pathname}
-  match="startsWith"
-  brandHref="/main"
-/>
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `items` | `SidebarItem[]` | `[]` | 메뉴 아이템 |
-| `activePath` | `string` | - | 현재 활성 경로 |
-| `match` | `'startsWith' \| 'exact'` | `'startsWith'` | 경로 매칭 방식 |
-| `brandHref` | `string` | `'/main'` | 로고 클릭 시 이동 경로 |
-| `onItemSelect` | `(href: string) => void` | - | 아이템 선택 핸들러 |
+| Category | Components |
+|----------|------------|
+| **General** | Button, Select |
+| **Form** | TextField, Checkbox, Radio, Switch, DatePicker, FileInput |
+| **Feedback** | Alert, Toast, Spinner, TopLoading |
+| **Navigation** | Pagination, Sidebar |
+| **Overlay** | Modal |
+| **Display** | Card |
 
----
-
-### Overlay
-
-#### Modal
-
-```tsx
-import { Modal } from '@bigtablet/design-system';
-
-const [isOpen, setIsOpen] = useState(false);
-
-<button onClick={() => setIsOpen(true)}>모달 열기</button>
-
-<Modal
-  open={isOpen}
-  onClose={() => setIsOpen(false)}
-  title="모달 제목"
-  width={600}
->
-  <p>모달 내용입니다.</p>
-</Modal>
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `open` | `boolean` | required | 열림 상태 |
-| `onClose` | `() => void` | - | 닫기 핸들러 |
-| `title` | `ReactNode` | - | 제목 |
-| `width` | `number \| string` | `520` | 모달 너비 |
-| `closeOnOverlay` | `boolean` | `true` | 오버레이 클릭 시 닫기 |
-
----
-
-### Display
-
-#### Card
-
-```tsx
-import { Card } from '@bigtablet/design-system';
-
-<Card heading="카드 제목">
-  <p>카드 내용입니다.</p>
-</Card>
-
-// 스타일 옵션
-<Card heading="제목" shadow="lg" padding="lg" bordered>
-  내용
-</Card>
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `heading` | `ReactNode` | - | 카드 제목 |
-| `shadow` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'sm'` | 그림자 |
-| `padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | 내부 여백 |
-| `bordered` | `boolean` | `false` | 테두리 표시 |
+👉 **[전체 컴포넌트 문서](./docs/COMPONENTS.md)**
 
 ---
 
-## Foundation (디자인 토큰)
+## 문서
 
-### SCSS 토큰 사용
-
-```scss
-@use "@bigtablet/design-system/scss/token" as token;
-
-.my-component {
-  color: token.$color_primary;
-  padding: token.$spacing_md;
-  border-radius: token.$radius_sm;
-  font-size: token.$font_size_base;
-}
-```
-
-### 주요 토큰
-
-| Category | Examples |
-|----------|----------|
-| **Colors** | `$color_primary`, `$color_error`, `$color_text_primary` |
-| **Spacing** | `$spacing_xs` (4px), `$spacing_sm` (8px), `$spacing_md` (16px) |
-| **Typography** | `$font_size_sm`, `$font_size_base`, `$font_weight_medium` |
-| **Radius** | `$radius_sm` (4px), `$radius_md` (8px), `$radius_lg` (12px) |
-| **Shadows** | `$shadow_sm`, `$shadow_md`, `$shadow_lg` |
-| **Z-Index** | `$z_dropdown`, `$z_modal`, `$z_toast` |
-
----
-
-## 프로젝트 구조
-
-```
-src/
-├── styles/
-│   ├── ts/              # TypeScript 디자인 토큰
-│   └── scss/            # SCSS 토큰 및 믹스인
-├── ui/
-│   ├── general/         # Button, Select
-│   ├── form/            # TextField, Checkbox, Radio, Switch, DatePicker, FileInput
-│   ├── feedback/        # Alert, Toast, Spinner, TopLoading
-│   ├── navigation/      # Pagination, Sidebar
-│   ├── overlay/         # Modal
-│   └── display/         # Card
-├── index.ts             # Pure React 진입점
-└── next.ts              # Next.js 진입점
-```
+| 문서 | 설명 |
+|------|------|
+| [Components](./docs/COMPONENTS.md) | 컴포넌트 API 및 사용법 |
+| [Vanilla JS](./docs/VANILLA.md) | HTML/CSS/JS 환경 가이드 |
+| [Architecture](./docs/ARCHITECTURE.md) | 프로젝트 구조 및 아키텍처 |
+| [Contributing](./docs/CONTRIBUTING.md) | 기여 가이드라인 |
+| [Testing](./docs/TESTING.md) | 테스트 작성 가이드 |
 
 ---
 
-## 개발 가이드
+## 개발
 
 ```bash
-# 저장소 클론
-git clone https://github.com/Bigtablet/bigtablet-design-system.git
-cd bigtablet-design-system
-
-# 의존성 설치
-pnpm install
-
-# Storybook 실행
-pnpm storybook
-
-# 빌드
-pnpm build
+pnpm install       # 의존성 설치
+pnpm storybook     # Storybook 실행 (port 6006)
+pnpm build         # 라이브러리 빌드
+pnpm test          # 테스트 실행
 ```
 
----
-
-## 기여하기
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feat/amazing-feature`)
-3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
-4. Push to the branch (`git push origin feat/amazing-feature`)
-5. Open a Pull Request to `develop` branch
-
-### Commit Convention
-
-| Label | Description |
-|-------|-------------|
-| `feat` | 새로운 기능 |
-| `fix` | 버그/코드 수정 |
-| `docs` | 문서 수정 |
-| `style` | 코드 스타일 변경 |
-| `config` | 설정 파일 수정 |
+👉 **[개발 환경 설정](./docs/CONTRIBUTING.md#개발-환경-설정)**
 
 ---
 

package/dist/index.css

@@ -431,6 +431,7 @@
   position: relative;
   display: inline-flex;
   align-items: center;
+  cursor: pointer;
 }
 .file_input:hover .file_input_label {
   border-color: rgba(0, 0, 0, 0.08);

package/dist/index.d.ts

@@ -8,6 +8,12 @@ interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
     padding?: "none" | "sm" | "md" | "lg";
     bordered?: boolean;
 }
+/**
+ * 카드 컴포넌트를 렌더링한다.
+ * 그림자/패딩/테두리 옵션을 조합해 레이아웃 컨테이너를 구성한다.
+ * @param props 카드 속성
+ * @returns 렌더링된 카드 UI
+ */
 declare const Card: ({ heading, shadow, padding, bordered, className, children, ...props }: CardProps) => react_jsx_runtime.JSX.Element;
 
 type AlertVariant = "info" | "success" | "warning" | "error";
@@ -26,16 +32,33 @@ interface AlertOptions {
 interface AlertContextValue {
     showAlert: (options: AlertOptions) => void;
 }
+/**
+ * AlertContext를 사용하는 훅.
+ * Provider 외부에서 호출되면 오류를 던진다.
+ * @returns alert 컨트롤러
+ */
 declare const useAlert: () => AlertContextValue;
+/**
+ * 알림 모달을 제어하는 Provider를 렌더링한다.
+ * 내부 상태를 통해 AlertModal 표시와 확인/취소 흐름을 관리한다.
+ * @param props Provider 속성
+ * @returns 렌더링된 Provider와 모달
+ */
 declare const AlertProvider: React.FC<{
     children: React.ReactNode;
 }>;
 
 interface SpinnerProps {
     size?: number;
-    /** Accessible label for the spinner (default: "Loading") */
+    /** 스피너 접근성 레이블 (기본값: "Loading") */
     ariaLabel?: string;
 }
+/**
+ * 스피너를 렌더링한다.
+ * 크기와 접근성 레이블을 적용한 뒤 상태 표시용 요소를 반환한다.
+ * @param props 스피너 속성
+ * @returns 렌더링된 스피너 요소
+ */
 declare const Spinner: ({ size, ariaLabel }: SpinnerProps) => react_jsx_runtime.JSX.Element;
 
 interface TopLoadingProps {
@@ -50,11 +73,23 @@ interface TopLoadingProps {
     /** 프로그레스 바의 접근성 레이블 (기본값: "Page loading") */
     ariaLabel?: string;
 }
+/**
+ * 상단 로딩바를 렌더링한다.
+ * 표시 여부와 진행률에 따라 determinate/indeterminate 상태를 구성한다.
+ * @param props 로딩바 속성
+ * @returns 렌더링된 로딩바 요소 또는 null
+ */
 declare const TopLoading: ({ progress, color, height, isLoading, ariaLabel, }: TopLoadingProps) => react_jsx_runtime.JSX.Element | null;
 
 interface ToastProviderProps {
     containerId?: string;
 }
+/**
+ * 토스트 컨테이너를 렌더링한다.
+ * 기본 옵션을 설정하고 전역 토스트 표시 영역을 제공한다.
+ * @param props 토스트 컨테이너 속성
+ * @returns 렌더링된 토스트 컨테이너
+ */
 declare const ToastProvider: ({ containerId }: ToastProviderProps) => react_jsx_runtime.JSX.Element;
 
 declare const useToast: (containerId?: string) => {
@@ -68,14 +103,20 @@ declare const useToast: (containerId?: string) => {
 interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
     variant?: "primary" | "secondary" | "ghost" | "danger";
     size?: "sm" | "md" | "lg";
-    /** Whether the button should take the full width of its container */
+    /** 버튼이 컨테이너의 전체 너비를 차지할지 여부 */
     fullWidth?: boolean;
     /**
-     * Custom width for the button
-     * @deprecated Use `fullWidth` prop or CSS instead
+     * 버튼의 커스텀 너비
+     * @deprecated `fullWidth` 사용 또는 CSS로 처리
      */
     width?: string;
 }
+/**
+ * 버튼을 렌더링한다.
+ * 전달된 props로 클래스 조합과 인라인 스타일을 계산한 뒤 버튼 요소를 반환한다.
+ * @param props 버튼 속성
+ * @returns 렌더링된 버튼 요소
+ */
 declare const Button: ({ variant, size, fullWidth, width, className, style, ...props }: ButtonProps) => react_jsx_runtime.JSX.Element;
 
 interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size"> {
@@ -83,18 +124,38 @@ interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>
     size?: "sm" | "md" | "lg";
     indeterminate?: boolean;
 }
+/**
+ * 체크박스를 렌더링한다.
+ * indeterminate 상태를 반영하고 라벨을 포함한 UI를 구성한다.
+ * @param props 체크박스 속성
+ * @param ref 입력 요소 참조
+ * @returns 렌더링된 체크박스 UI
+ */
 declare const Checkbox: React.ForwardRefExoticComponent<CheckboxProps & React.RefAttributes<HTMLInputElement>>;
 
 interface FileInputProps extends React.InputHTMLAttributes<HTMLInputElement> {
     label?: string;
     onFiles?: (files: FileList | null) => void;
 }
+/**
+ * 파일 입력 컴포넌트를 렌더링한다.
+ * 내부 input 변경을 감지해 파일 목록을 콜백으로 전달한다.
+ * @param props 파일 입력 속성
+ * @returns 렌더링된 파일 입력 UI
+ */
 declare const FileInput: ({ label, onFiles, className, disabled, ...props }: FileInputProps) => react_jsx_runtime.JSX.Element;
 
 interface RadioProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size"> {
     label?: React.ReactNode;
     size?: "sm" | "md" | "lg";
 }
+/**
+ * 라디오 버튼을 렌더링한다.
+ * 크기별 클래스와 라벨을 조합해 UI를 구성한다.
+ * @param props 라디오 속성
+ * @param ref 입력 요소 참조
+ * @returns 렌더링된 라디오 UI
+ */
 declare const Radio: React.ForwardRefExoticComponent<RadioProps & React.RefAttributes<HTMLInputElement>>;
 
 type SelectSize = "sm" | "md" | "lg";
@@ -119,6 +180,12 @@ interface SelectProps {
     className?: string;
     textAlign?: "left" | "center";
 }
+/**
+ * 셀렉트 컴포넌트를 렌더링한다.
+ * 제어형/비제어형 상태를 정리하고, 키보드/마우스 상호작용과 드롭다운 표시를 관리한다.
+ * @param props 셀렉트 속성
+ * @returns 렌더링된 셀렉트 UI
+ */
 declare const Select: ({ id, label, placeholder, options, value, onChange, defaultValue, disabled, size, variant, fullWidth, className, textAlign, }: SelectProps) => react_jsx_runtime.JSX.Element;
 
 interface SwitchProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onChange"> {
@@ -127,9 +194,16 @@ interface SwitchProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>
     onChange?: (checked: boolean) => void;
     size?: "sm" | "md" | "lg";
     disabled?: boolean;
-    /** Accessible label for the switch (for screen readers) */
+    /** 스위치 접근성 레이블(스크린 리더용) */
     ariaLabel: string;
 }
+/**
+ * 스위치를 렌더링한다.
+ * 제어형/비제어형 상태를 판별해 토글 로직을 수행하고 버튼 형태의 스위치 UI를 반환한다.
+ * @param props 스위치 속성
+ * @param ref 버튼 참조
+ * @returns 렌더링된 스위치 요소
+ */
 declare const Switch: React.ForwardRefExoticComponent<SwitchProps & React.RefAttributes<HTMLButtonElement>>;
 
 type TextFieldVariant = "outline" | "filled" | "ghost";
@@ -149,6 +223,13 @@ interface TextFieldProps extends Omit<React.InputHTMLAttributes<HTMLInputElement
     defaultValue?: string;
     transformValue?: (value: string) => string;
 }
+/**
+ * 텍스트 필드를 렌더링한다.
+ * 제어형/비제어형 값을 동기화하고, 조합 입력(IME)을 고려해 변경 이벤트를 전달한다.
+ * @param props 텍스트 필드 속성
+ * @param ref 입력 요소 참조
+ * @returns 렌더링된 텍스트 필드 UI
+ */
 declare const TextField: React.ForwardRefExoticComponent<TextFieldProps & React.RefAttributes<HTMLInputElement>>;
 
 type DatePickerMode = "year-month" | "year-month-day";
@@ -163,14 +244,20 @@ interface DatePickerProps {
     minDate?: string;
     selectableRange?: SelectableRange;
     disabled?: boolean;
-    /** Whether the date picker should take the full width of its container */
+    /** 데이트 피커가 컨테이너의 전체 너비를 차지할지 여부 */
     fullWidth?: boolean;
     /**
-     * Custom width for the date picker
-     * @deprecated Use `fullWidth` prop or CSS instead
+     * 데이트 피커의 커스텀 너비
+     * @deprecated `fullWidth` 사용 또는 CSS로 처리
      */
     width?: number | string;
 }
+/**
+ * 연/월/일 선택형 데이트 피커를 렌더링한다.
+ * 입력 값과 선택 범위를 기준으로 옵션을 계산하고, 선택 변경을 상위로 전달한다.
+ * @param props 데이트 피커 속성
+ * @returns 렌더링된 데이트 피커 UI
+ */
 declare const DatePicker: ({ label, value, onChange, mode, startYear, endYear, minDate, selectableRange, disabled, fullWidth, width, }: DatePickerProps) => react_jsx_runtime.JSX.Element;
 
 interface PaginationProps {
@@ -178,6 +265,12 @@ interface PaginationProps {
     totalPages: number;
     onChange: (page: number) => void;
 }
+/**
+ * 페이지네이션을 렌더링한다.
+ * 이전/다음 버튼과 페이지 목록을 구성해 전달된 콜백으로 페이지 변경을 전달한다.
+ * @param props 페이지네이션 속성
+ * @returns 렌더링된 페이지네이션 UI
+ */
 declare const Pagination: ({ page, totalPages, onChange }: PaginationProps) => react_jsx_runtime.JSX.Element;
 
 interface ModalProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
@@ -186,9 +279,15 @@ interface ModalProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title">
     closeOnOverlay?: boolean;
     width?: number | string;
     title?: React.ReactNode;
-    /** Accessible label for the modal (default uses title or "Dialog") */
+    /** 모달 접근성 레이블(기본값: title 또는 "Dialog") */
     ariaLabel?: string;
 }
+/**
+ * 모달을 렌더링한다.
+ * 포커스 트랩과 스크롤 잠금을 적용하고, 열림 상태에 따라 오버레이/패널을 구성한다.
+ * @param props 모달 속성
+ * @returns 열림 상태일 때 렌더링된 모달, 닫힘 상태면 null
+ */
 declare const Modal: ({ open, onClose, closeOnOverlay, width, title, children, className, ariaLabel, ...props }: ModalProps) => react_jsx_runtime.JSX.Element | null;
 
 export { AlertProvider, Button, Card, Checkbox, DatePicker, FileInput, Modal, Pagination, Radio, Select, type SelectOption, Spinner, Switch, TextField, ToastProvider, TopLoading, useAlert, useToast };

package/dist/next.d.ts

@@ -26,6 +26,12 @@ interface SidebarProps {
     match?: MatchMode;
     brandHref?: string;
 }
+/**
+ * 사이드바를 렌더링한다.
+ * 활성 경로를 기준으로 메뉴 상태를 계산하고 그룹 열림/닫힘을 관리한다.
+ * @param props 사이드바 속성
+ * @returns 렌더링된 사이드바 UI
+ */
 declare const Sidebar: ({ items, activePath, onItemSelect, className, style, match, brandHref, }: SidebarProps) => react_jsx_runtime.JSX.Element;
 
 export { Sidebar, type SidebarItem, type SidebarProps };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bigtablet/design-system",
-  "version": "1.18.0",
+  "version": "1.18.2",
   "description": "Bigtablet Design System UI Components",
   "type": "module",
   "types": "dist/index.d.ts",