ERP-node/frontend/lib/registry/components/v2-table-grouped/README.md

v2-table-grouped (그룹화 테이블)

개요

데이터를 특정 컬럼 기준으로 그룹화하여 접기/펼치기 기능을 제공하는 테이블 컴포넌트입니다.

주요 기능

• 그룹화: 지정된 컬럼 기준으로 데이터를 그룹핑
• 접기/펼치기: 그룹 헤더 클릭으로 하위 항목 토글
• 그룹 요약: 그룹별 개수, 합계, 평균, 최대/최소값 표시
• 체크박스 선택: 그룹 단위 또는 개별 항목 선택
• 전체 펼치기/접기: 모든 그룹 일괄 토글 버튼

사용 예시

import { TableGroupedComponent } from "./TableGroupedComponent";

<TableGroupedComponent
  config={{
    selectedTable: "production_plan_mng",
    groupConfig: {
      groupByColumn: "item_code",
      groupLabelFormat: "{item_name} ({item_code})",
      defaultExpanded: true,
      summary: {
        showCount: true,
        sumColumns: ["quantity"],
      },
    },
    columns: [
      { columnName: "plan_no", displayName: "계획번호", visible: true },
      { columnName: "plan_date", displayName: "계획일", visible: true },
      { columnName: "quantity", displayName: "수량", visible: true, format: "number" },
    ],
    showCheckbox: true,
    checkboxMode: "multi",
    showExpandAllButton: true,
  }}
  onSelectionChange={(event) => console.log("선택:", event.selectedItems)}
  onRowClick={(event) => console.log("행 클릭:", event.row)}
/>

설정 옵션

기본 설정

옵션	타입	기본값	설명
selectedTable	string	-	데이터 테이블명
useCustomTable	boolean	false	커스텀 테이블 사용 여부
customTableName	string	-	커스텀 테이블명
columns	ColumnConfig[]	[]	표시할 컬럼 설정

그룹화 설정 (groupConfig)

옵션	타입	기본값	설명
groupByColumn	string	-	그룹화 기준 컬럼 (필수)
groupLabelFormat	string	"{value}"	그룹 라벨 형식
defaultExpanded	boolean	true	초기 펼침 상태
sortDirection	"asc" | "desc"	"asc"	그룹 정렬 방향
summary.showCount	boolean	true	개수 표시 여부
summary.sumColumns	string[]	[]	합계 컬럼 목록
summary.avgColumns	string[]	[]	평균 컬럼 목록

표시 설정

옵션	타입	기본값	설명
showCheckbox	boolean	false	체크박스 표시
checkboxMode	"single" | "multi"	"multi"	선택 모드
showExpandAllButton	boolean	true	전체 펼치기/접기 버튼
groupHeaderStyle	"default" | "compact" | "card"	"default"	그룹 헤더 스타일
rowClickable	boolean	true	행 클릭 가능 여부
maxHeight	number	600	최대 높이 (px)
emptyMessage	string	"데이터가 없습니다."	빈 데이터 메시지

이벤트

onSelectionChange

선택 상태가 변경될 때 호출됩니다.

interface SelectionChangeEvent {
  selectedGroups: string[];  // 선택된 그룹 키 목록
  selectedItems: any[];      // 선택된 아이템 전체
  isAllSelected: boolean;    // 전체 선택 여부
}

onGroupToggle

그룹 펼치기/접기 시 호출됩니다.

interface GroupToggleEvent {
  groupKey: string;   // 그룹 키
  expanded: boolean;  // 펼침 상태
}

onRowClick

행 클릭 시 호출됩니다.

interface RowClickEvent {
  row: any;           // 클릭된 행 데이터
  groupKey: string;   // 그룹 키
  indexInGroup: number; // 그룹 내 인덱스
}

그룹 라벨 형식

groupLabelFormat에서 사용 가능한 플레이스홀더:

• {value}: 그룹화 컬럼의 값
• {컬럼명}: 해당 컬럼의 값

예시:

groupLabelFormat: "{item_name} ({item_code}) - {category}"
// 결과: "제품A (P001) - 완제품"

파일 구조

v2-table-grouped/
├── index.ts                    # Definition
├── types.ts                    # 타입 정의
├── config.ts                   # 기본 설정값
├── TableGroupedComponent.tsx   # 메인 컴포넌트
├── TableGroupedConfigPanel.tsx # 설정 패널
├── TableGroupedRenderer.tsx    # 레지스트리 등록
├── components/
│   └── GroupHeader.tsx         # 그룹 헤더
├── hooks/
│   └── useGroupedData.ts       # 그룹화 로직 훅
└── README.md

v2-table-list와의 차이점

항목	v2-table-list	v2-table-grouped
데이터 구조	플랫 리스트	계층 구조 (그룹 > 아이템)
렌더링	행 단위	그룹 헤더 + 상세 행
선택	개별 행	그룹 단위 / 개별 단위
요약	전체 합계 (선택)	그룹별 요약
용도	일반 데이터 목록	카테고리별 분류 데이터

관련 컴포넌트

• v2-table-list: 기본 테이블 (그룹화 없음)
• v2-pivot-grid: 피벗 테이블 (다차원 집계)
• v2-split-panel-layout: 마스터-디테일 레이아웃