# TableList 컴포넌트

데이터베이스 테이블의 데이터를 목록으로 표시하는 고급 테이블 컴포넌트

## 개요

- **ID**: `table-list`
- **카테고리**: display
- **웹타입**: table
- **작성자**: 개발팀
- **버전**: 1.0.0

## 특징

- ✅ **동적 테이블 연동**: 데이터베이스 테이블 자동 로드
- ✅ **고급 페이지네이션**: 대용량 데이터 효율적 처리
- ✅ **실시간 검색**: 빠른 데이터 검색 및 필터링
- ✅ **컬럼 커스터마이징**: 표시/숨김, 순서 변경, 정렬
- ✅ **정렬 기능**: 컬럼별 오름차순/내림차순 정렬
- ✅ **반응형 디자인**: 다양한 화면 크기 지원
- ✅ **다양한 테마**: 기본, 줄무늬, 테두리, 미니멀 테마
- ✅ **실시간 새로고침**: 데이터 자동/수동 새로고침

## 사용법

### 기본 사용법

```tsx
import { TableListComponent } from "@/lib/registry/components/table-list";

<TableListComponent
  component={{
    id: "my-table-list",
    type: "widget",
    webType: "table",
    position: { x: 100, y: 100, z: 1 },
    size: { width: 800, height: 400 },
    config: {
      selectedTable: "users",
      title: "사용자 목록",
      showHeader: true,
      showFooter: true,
      autoLoad: true,
      pagination: {
        enabled: true,
        pageSize: 20,
        showSizeSelector: true,
        showPageInfo: true,
        pageSizeOptions: [10, 20, 50, 100],
      },
      filter: {
        enabled: true,
        quickSearch: true,
        advancedFilter: false,
      },
    },
  }}
  isDesignMode={false}
/>;
```

## 주요 설정 옵션

### 기본 설정

| 속성          | 타입                            | 기본값 | 설명                         |
| ------------- | ------------------------------- | ------ | ---------------------------- |
| selectedTable | string                          | -      | 표시할 데이터베이스 테이블명 |
| title         | string                          | -      | 테이블 제목                  |
| showHeader    | boolean                         | true   | 헤더 표시 여부               |
| showFooter    | boolean                         | true   | 푸터 표시 여부               |
| autoLoad      | boolean                         | true   | 자동 데이터 로드             |
| height        | "auto" \| "fixed" \| "viewport" | "auto" | 높이 설정 모드               |
| fixedHeight   | number                          | 400    | 고정 높이 (px)               |

### 페이지네이션 설정

| 속성                        | 타입     | 기본값         | 설명                    |
| --------------------------- | -------- | -------------- | ----------------------- |
| pagination.enabled          | boolean  | true           | 페이지네이션 사용 여부  |
| pagination.pageSize         | number   | 20             | 페이지당 표시 항목 수   |
| pagination.showSizeSelector | boolean  | true           | 페이지 크기 선택기 표시 |
| pagination.showPageInfo     | boolean  | true           | 페이지 정보 표시        |
| pagination.pageSizeOptions  | number[] | [10,20,50,100] | 선택 가능한 페이지 크기 |

### 컬럼 설정

| 속성                  | 타입                                                    | 설명                |
| --------------------- | ------------------------------------------------------- | ------------------- |
| columns               | ColumnConfig[]                                          | 컬럼 설정 배열      |
| columns[].columnName  | string                                                  | 데이터베이스 컬럼명 |
| columns[].displayName | string                                                  | 화면 표시명         |
| columns[].visible     | boolean                                                 | 표시 여부           |
| columns[].sortable    | boolean                                                 | 정렬 가능 여부      |
| columns[].searchable  | boolean                                                 | 검색 가능 여부      |
| columns[].align       | "left" \| "center" \| "right"                           | 텍스트 정렬         |
| columns[].format      | "text" \| "number" \| "date" \| "currency" \| "boolean" | 데이터 형식         |
| columns[].width       | number                                                  | 컬럼 너비 (px)      |
| columns[].order       | number                                                  | 표시 순서           |

### 필터 설정

| 속성                     | 타입     | 기본값 | 설명                |
| ------------------------ | -------- | ------ | ------------------- |
| filter.enabled           | boolean  | true   | 필터 기능 사용 여부 |
| filter.quickSearch       | boolean  | true   | 빠른 검색 사용 여부 |
| filter.advancedFilter    | boolean  | false  | 고급 필터 사용 여부 |
| filter.filterableColumns | string[] | []     | 필터 가능 컬럼 목록 |

### 스타일 설정

| 속성                     | 타입                                              | 기본값    | 설명                |
| ------------------------ | ------------------------------------------------- | --------- | ------------------- |
| tableStyle.theme         | "default" \| "striped" \| "bordered" \| "minimal" | "default" | 테이블 테마         |
| tableStyle.headerStyle   | "default" \| "dark" \| "light"                    | "default" | 헤더 스타일         |
| tableStyle.rowHeight     | "compact" \| "normal" \| "comfortable"            | "normal"  | 행 높이             |
| tableStyle.alternateRows | boolean                                           | true      | 교대로 행 색상 변경 |
| tableStyle.hoverEffect   | boolean                                           | true      | 마우스 오버 효과    |
| tableStyle.borderStyle   | "none" \| "light" \| "heavy"                      | "light"   | 테두리 스타일       |
| stickyHeader             | boolean                                           | false     | 헤더 고정           |

## 이벤트

- `onRowClick`: 행 클릭 시
- `onRowDoubleClick`: 행 더블클릭 시
- `onSelectionChange`: 선택 변경 시
- `onPageChange`: 페이지 변경 시
- `onSortChange`: 정렬 변경 시
- `onFilterChange`: 필터 변경 시
- `onRefresh`: 새로고침 시

## API 연동

### 테이블 목록 조회

```
GET /api/tables
```

### 테이블 컬럼 정보 조회

```
GET /api/tables/{tableName}/columns
```

### 테이블 데이터 조회

```
GET /api/tables/{tableName}/data?page=1&limit=20&search=&sortBy=&sortDirection=
```

## 사용 예시

### 1. 기본 사용자 목록

```tsx
<TableListComponent
  component={{
    id: "user-list",
    config: {
      selectedTable: "users",
      title: "사용자 관리",
      pagination: { enabled: true, pageSize: 25 },
      filter: { enabled: true, quickSearch: true },
      columns: [
        { columnName: "id", displayName: "ID", visible: true, sortable: true },
        { columnName: "name", displayName: "이름", visible: true, sortable: true },
        { columnName: "email", displayName: "이메일", visible: true, sortable: true },
        { columnName: "created_at", displayName: "가입일", visible: true, format: "date" },
      ],
    },
  }}
/>
```

### 2. 매출 데이터 (통화 형식)

```tsx
<TableListComponent
  component={{
    id: "sales-list",
    config: {
      selectedTable: "sales",
      title: "매출 현황",
      tableStyle: { theme: "striped", rowHeight: "comfortable" },
      columns: [
        { columnName: "product_name", displayName: "상품명", visible: true },
        { columnName: "amount", displayName: "금액", visible: true, format: "currency", align: "right" },
        { columnName: "quantity", displayName: "수량", visible: true, format: "number", align: "center" },
      ],
    },
  }}
/>
```

### 3. 고정 높이 테이블

```tsx
<TableListComponent
  component={{
    id: "fixed-table",
    config: {
      selectedTable: "products",
      height: "fixed",
      fixedHeight: 300,
      stickyHeader: true,
      pagination: { enabled: false },
    },
  }}
/>
```

## 상세설정 패널

컴포넌트 설정 패널은 5개의 탭으로 구성되어 있습니다:

1. **기본 탭**: 테이블 선택, 제목, 표시 설정, 높이, 페이지네이션
2. **컬럼 탭**: 컬럼 추가/제거, 표시 설정, 순서 변경, 형식 지정
3. **필터 탭**: 검색 및 필터 옵션 설정
4. **액션 탭**: 행 액션 버튼, 일괄 액션 설정
5. **스타일 탭**: 테마, 행 높이, 색상, 효과 설정

## 개발자 정보

- **생성일**: 2025-09-12
- **CLI 명령어**: `node scripts/create-component.js table-list "테이블 리스트" "데이터베이스 테이블의 데이터를 목록으로 표시하는 컴포넌트" display`
- **경로**: `lib/registry/components/table-list/`

## API 요구사항

이 컴포넌트가 정상 작동하려면 다음 API 엔드포인트가 구현되어 있어야 합니다:

- `GET /api/tables` - 사용 가능한 테이블 목록
- `GET /api/tables/{tableName}/columns` - 테이블 컬럼 정보
- `GET /api/tables/{tableName}/data` - 테이블 데이터 (페이징, 검색, 정렬 지원)

## 관련 문서

- [컴포넌트 시스템 가이드](../../docs/컴포넌트_시스템_가이드.md)
- [API 문서](https://docs.example.com/api/tables)
- [개발자 문서](https://docs.example.com/components/table-list)