Analytics

TableToolbar

Dark Mode

테이블 상단에 배치되는 기능 바입니다. 빌트인 필터·검색·정렬 기능과 커스텀 액션 슬롯을 지원합니다. useDataTable hook의 toolbarProps를 스프레드하면 자동 연동됩니다.

import { TableToolbar } from "@/shared/ui/widget/analytics/table"

빌트인 기능 전체

다중 정렬, 필터 드롭다운, 필드 가시성, 검색 범위 선택, 커스텀 액션 버튼이 모두 포함된 형태입니다. useDataTable의 toolbarProps를 스프레드하면 이 구성이 자동으로 적용됩니다.

toolbarProps 스프레드 (권장)

// useDataTable의 toolbarProps를 그대로 스프레드
const table = useDataTable({ data, columns, pageSize: 10 });

<TableToolbar
  {...table.toolbarProps}
  actions={<ToolbarButton icon={FolderDown} label="내보내기" />}
/>

심플 모드 (검색 + 커스텀 액션)

빌트인 기능 없이 검색과 커스텀 actions만 사용하는 가장 간단한 형태입니다. 빌트인 props를 전달하지 않으면 해당 버튼이 자동으로 숨겨집니다.

심플 모드

// 빌트인 기능 없이 검색 + 커스텀 액션만
<TableToolbar
  searchPlaceholder="포트폴리오 검색..."
  actions={<ToolbarButton icon={Plus} label="추가" />}
/>

개별 Props 직접 구성

useDataTable 없이 직접 상태를 관리할 때의 전체 props 구성 예시입니다.

수동 구성

// 빌트인 기능을 개별 props로 직접 구성
<TableToolbar
  // 검색
  searchValue={search}
  onSearchChange={setSearch}
  searchKey={searchKey}
  onSearchKeyChange={setSearchKey}
  searchableColumns={[
    { key: "company", label: "회사명" },
    { key: "sector",  label: "섹터" },
  ]}
  // 필터
  filters={filters}
  onFilterChange={handleFilter}
  onClearFilters={() => setFilters([])}
  filterableColumns={filterableColumns}
  activeFilterCount={filters.length}
  // 다중 정렬
  sortConfigs={sortConfigs}
  onSortConfigsChange={setSortConfigs}
  sortableColumns={sortableColumns}
  // 필드 가시성
  visibleKeys={visibleKeys}
  onVisibleKeysChange={setVisibleKeys}
  allColumns={allColumns}
  // 커스텀 슬롯
  actions={<ToolbarButton icon={FolderDown} label="내보내기" />}
/>

빌트인 기능 상세

1. 필터 드롭다운

filterableColumns에 지정된 각 컬럼의 고유값을 체크박스로 표시합니다. 여러 컬럼에 동시에 필터를 적용할 수 있으며, 활성 필터 수가 뱃지로 표시됩니다.

관련 props: filterableColumns, filters, onFilterChange, onClearFilters, activeFilterCount

2. 검색 범위 선택

검색 바의 / 키를 클릭하면 검색 대상 컬럼을 선택하는 팝오버가 열립니다. 선택하면 해당 컬럼만 대상으로 검색합니다. null이면 전체 컬럼 대상으로 검색합니다.

관련 props: searchableColumns, searchKey, onSearchKeyChange

3. 보여줄 필드 선택

'필드' 드롭다운으로 테이블에 표시할 컬럼을 토글합니다. 기본값은 전체 선택이며, 숨긴 컬럼 수가 뱃지로 표시됩니다.

관련 props: allColumns, visibleKeys, onVisibleKeysChange

4. 다중 정렬

'정렬' 버튼 클릭 시 다중 정렬 모달이 열립니다. 1차·2차·3차 정렬 컬럼을 추가/삭제/순서 변경할 수 있으며, 각각 오름차순/내림차순을 선택합니다.

관련 props: sortableColumns, sortConfigs, onSortConfigsChange

5. 커스텀 슬롯

actions (중앙), trailing (우측 끝) 슬롯으로 커스텀 버튼을 배치할 수 있습니다. ToolbarButton 컴포넌트로 Toolbar UI와 일관된 버튼을 만들 수 있습니다.

Props

TableToolbar

Prop	Type	Required	Default	설명
`searchValue`	`string`	—	''	검색 입력 값.
`onSearchChange`	`(value: string) => void`	—	—	검색 값 변경 콜백.
`searchPlaceholder`	`string`	—	—	검색 placeholder. 미지정 시 검색 범위에 따라 자동 생성됩니다.
`searchKey`	`string \| null`	—	null	현재 검색 대상 단일 컬럼 키. null이면 전체 컬럼 검색.
`onSearchKeyChange`	`(key: string \| null) => void`	—	—	검색 대상 변경 콜백. 설정 시 검색 바에 / 키 팝오버가 활성화됩니다.
`searchableColumns`	`{ key: string; label: string }[]`	—	—	검색 범위 선택 팝오버에 표시할 컬럼 목록.
`filters`	`FilterValue[]` { columnKey: string; values: string[] }[]	—	—	현재 활성 필터 목록.
`onFilterChange`	`(columnKey: string, values: string[]) => void`	—	—	필터 변경 콜백. 설정 시 필터 드롭다운이 표시됩니다.
`filterableColumns`	`{ key: string; label: string; options: string[] }[]`	—	—	필터 가능한 컬럼과 고유값 목록. useDataTable이 자동 생성합니다.
`activeFilterCount`	`number`	—	0	활성 필터 수. 뱃지로 표시됩니다.
`sortConfigs`	`SortConfig[]` { key: string; direction: 'asc' \| 'desc' }[]	—	—	현재 다중 정렬 설정. 설정 시 정렬 버튼 + 모달이 표시됩니다.
`onSortConfigsChange`	`(configs: SortConfig[]) => void`	—	—	다중 정렬 변경 콜백. 모달에서 정렬 추가/삭제/순서 변경 시 호출됩니다.
`sortableColumns`	`{ key: string; label: string }[]`	—	—	정렬 가능 컬럼 목록. 정렬 모달의 드롭다운에 표시됩니다.
`availableSources`	`{ id: string; label: string; color?: string }[]`	—	—	선택 가능한 데이터 소스 목록. 설정 시 소스 선택 팝오버가 표시됩니다.
`activeSources`	`string[]`	—	—	현재 활성 소스 ID 목록.
`onToggleSource`	`(id: string) => void`	—	—	소스 토글 콜백. 소스 선택 팝오버에서 체크박스 변경 시 호출됩니다.
`actions`	`ReactNode`	—	—	커스텀 액션 버튼 영역 (빌트인 기능 뒤).
`trailing`	`ReactNode`	—	—	우측 끝 커스텀 영역 (내보내기 버튼 등).
`visibleKeys`	`string[]`	—	—	현재 표시 중인 컬럼 키 목록. 설정 시 필드 가시성 드롭다운이 표시됩니다.
`onVisibleKeysChange`	`(keys: string[]) => void`	—	—	컬럼 가시성 변경 콜백.
`allColumns`	`{ key: string; label: string }[]`	—	—	전체 컬럼 목록. 필드 가시성 드롭다운에 표시됩니다.
`className`	`string`	—	—	추가 클래스.

ToolbarButton

Prop	Type	Required	Default	설명
`icon`	`ComponentType<{ className?: string }>`	✓	—	아이콘 컴포넌트.
`onClick`	`() => void`	—	—	클릭 핸들러.
`label`	`string`	—	—	접근성 라벨.
`active`	`boolean`	—	—	활성 상태 스타일 적용.
`children`	`ReactNode`	—	—	아이콘 옆에 표시할 텍스트 라벨.