WebPivot — React Data Grid + Pivot Table

Vite + React + TypeScript + Tailwind pivot & data grid — alanları sürükle-bırakla Filter / Rows / Columns / Values'a taşı, 14 agg, Show Values As, sorting/filtering, virtualized 1M satır, Excel export.

Kurulum (npm)

npm install @nuhc/webpivot
# peer
npm install react react-dom

@nuhc/webpivot Tailwind tabanlıdır — tüketicide Tailwind yoksa sadece CSS'i import etmen yeterli, Tailwind kurmana gerek yok:

import '@nuhc/webpivot/dist/webpivot.css'

Tailwind kullanıyorsan zaten aynı sınıflar çalışır, ekstra adım yok.

Hızlı Başlangıç

import { WebPivot } from '@nuhc/webpivot'
import '@nuhc/webpivot/dist/webpivot.css'

const data = [
  { Country: 'France', Year: 'FY 2015', Amount: 52824, Sold: 31 },
  { Country: 'Germany', Year: 'FY 2016', Amount: 98000, Sold: 60 },
]

function App() {
  return (
    <WebPivot
      data={data}
      initialConfig={{
        rows: ['Country'],
        columns: ['Year'],
        values: [{ field: 'Amount', agg: 'sum', label: 'Amount' }],
      }}
      onChange={(cfg) => console.log(cfg)}
    />
  )
}

API

<WebPivot /> Props — src/components/WebPivot/types.ts:49

| Prop | Tip | Açık. | |------|-----|-------| | data | Record<string,any>[] | Kaynak veri | | fields | FieldDef[] | Manuel override; yoksa inferFields(data) otomatik (string/number/date/boolean + distinctCount, data değişince güncellenir) | | initialConfig | Partial<PivotConfig> | filters, rows, columns, values, filterValues, sorts, topN, dateGroups, calculatedFields, conditionalRules | | onChange | (cfg: PivotConfig)=>void | Config her değiştiğinde | | onDrillThrough | (info)=>void | Hücre çift tık → {rowKey,colKey,value,rows} | | enableExport | boolean | default true → toolbar Excel butonu | | className | string | wrapper |

PivotConfig — önemli alanlar

type Agg = 'sum'|'count'|'avg'|'min'|'max'|'distinctCount'|'product'|'median'|'mode'|'stdDev'|'variance'|'percentile'
type ShowAs = 'none'|'percentGrand'|'percentRow'|'percentCol'|'runningRow'|'runningCol'
type DateGroup = 'none'|'year'|'quarter'|'month'|'day'

interface ValueField { field:string; agg:Agg; label?:string; showAs?:ShowAs; percentile?:number }

interface PivotConfig {
  filters: string[]; rows: string[]; columns: string[]; values: ValueField[]
  filterValues?: Record<string, Set<string>> // member filter (modal checkbox)
  sorts?: {field:string; dir:'asc'|'desc'; byValue?:string}[]
  topN?: Record<string,{n:number; dir:'top'|'bottom'; byValue:string}>
  dateGroups?: Record<string, DateGroup>
  calculatedFields?: {name:string; label:string; formula:string}[] // "Amount * 0.2"
  conditionalRules?: {valueField:string; op:'>'|'<'|...; value:number; style:{bg?:string; color?:string}}[]
}

Engine (headless) — doğrudan da kullanılabilir

import { buildPivot, inferFields, aggregate, exportToExcel } from '@nuhc/webpivot'

const fields = inferFields(data) // FieldDef[]
const result = buildPivot(data, { rows:['Country'], columns:['Year'], values:[{field:'Amount', agg:'sum'}] })
// result: { rowKeys, colKeys, matrix, displayMatrix, rowTotals, colTotals, grandTotals, filteredData }

import { WebPivot } from '@nuhc/webpivot' // displayMatrix zaten ShowAs dönüşmüş

// Excel: pivot + RawData sekmeleri, bold header, number format
import { exportToExcel } from '@nuhc/webpivot'
await exportToExcel(result, 'Rapor', data)

// sadece agg
import { aggregate } from '@nuhc/webpivot'
aggregate([1,2,3], 'median') // 2

Özellikler

• V1: Otomatik field inference, DnD 4 zone (Filters/Rows/Columns/Values), 6 agg, buildPivot Map O(n), virtualized PivotGrid.tsx:28 (36px row, 480px viewport, overscan 8 → 1M distinct row'da ~30 DOM), Excel Pivot + RawData.
• V2: 14 agg (product, median, mode, stdDev, variance, percentile), Show Values As, sorting (↑/↓), member filter modal + TopN, date grouping, calculated fields (Formula), conditional formatting (hücre bg), drill-through (çift tık modal, 200 satır).
• Values boşken: rows/columns/filters doluysa otomatik Count ile sayım gösterir (tek başına boşsa prompt).
• Veri değişince field list otomatik güncellenir — usePivotState.ts:16.

Geliştirme

npm install
npm run dev      # demo app http://localhost:5173 — 8 / 100 / 1k / 10k / 100k stress
npm run test     # 6 dosya 39 test
npm run build    # app build (vite)
npm run build:lib # npm için lib build → dist/webpivot.es.js, dist/webpivot.cjs, dist/webpivot.css, dist/index.d.ts
npm run pack:dry # npm pack içeriğini gör

Dosya Haritası

• src/index.ts — public entry (npm)
• src/components/WebPivot/types.ts — tipler
• src/engine/* — inferFields, aggregators, pivotEngine, exportExcel
• src/hooks/* — usePivotState, useExcelExport
• vite.config.lib.ts — lib build (external: react), dts rollup
• dist/webpivot.es.js, dist/webpivot.cjs, dist/webpivot.css, dist/index.d.ts — yayınlanan artefaktlar