#3-3. TanStack API 호환과 컴포넌트 2026-03-02 ~ 03-05

#TanStack Table API 호환: 왜?

Canvas + WASM 테이블을 만들어도 아무도 안 쓰면 의미가 없다.

TanStack Table은 React 테이블 생태계에서 사실상 표준이다. createColumnHelper, useReactTable, getCoreRowModel 같은 API에 익숙한 개발자가 많다.

이 API를 그대로 쓸 수 있게 하면 마이그레이션 비용이 0에 가까워진다. "import 경로만 바꾸면 Canvas 테이블이 된다"는 게 목표였다.

// TanStack Table 스타일 그대로
import { Grid, createColumnHelper } from "@ohah/react-wasm-table";

const helper = createColumnHelper<Person>();
const columns = [
  helper.accessor("name", { header: "이름" }),
  helper.accessor("status", {
    cell: ({ getValue }) => <Badge value={getValue()} />
  }),
];

<Grid data={data} columns={columns} width={600} height={400} />

#Row Model 호환

TanStack의 Row Model 개념도 그대로 가져왔다:

• getCoreRowModel — 기본
• getSortedRowModel — 정렬 (WASM에서 실행)
• getFilteredRowModel — 필터 (WASM에서 실행)
• getExpandedRowModel — 트리/확장
• getPaginationRowModel — 페이지네이션
• getGroupedRowModel — 그룹핑
• getFacetedRowModel — 패싯 (고유값 집계)

정렬과 필터가 WASM에서 실행된다는 게 핵심이다. TanStack에서는 JS로 정렬하는데, 여기서는 Columnar Store의 인덱스 배열을 WASM에서 정렬한다. 데이터 자체를 옮기는 게 아니라 u32 인덱스만 재배열하니까 빠르다.

#Tree-Shakeable 모듈 분리

라이브러리가 커지면서 번들 사이즈가 고민이 됐다. 23개 Canvas 컴포넌트를 다 쓰는 사용자는 없을 테니까.

tsdown으로 subpath export를 설정했다:

@ohah/react-wasm-table          # 코어
@ohah/react-wasm-table/wasm     # WASM 로더
@ohah/react-wasm-table/sorting  # 정렬 Row Model
@ohah/react-wasm-table/filtering # 필터 Row Model
@ohah/react-wasm-table/grouping # 그룹핑 Row Model
@ohah/react-wasm-table/selection # 셀렉션
@ohah/react-wasm-table/clipboard # 클립보드
@ohah/react-wasm-table/renderers # Canvas 렌더러

안 쓰는 기능은 번들에 안 들어간다. sorting만 import하면 filtering 코드는 포함되지 않는다.

#트러블슈팅: WASM 로딩

WASM 파일은 비동기로 로드해야 한다. fetch → WebAssembly.instantiate 과정이 필요한데, React 컴포넌트 라이프사이클과 맞물리면 타이밍 이슈가 생긴다.

처음에는 <Grid> 컴포넌트 마운트 시 WASM을 로드했는데, 로딩 완료 전에 데이터가 들어오면 크래시가 났다.

해결책은 @ohah/react-wasm-table/wasm을 별도 엔트리로 분리하고, 앱 초기화 시점에 미리 로드하게 한 것이다. WASM이 준비되지 않으면 <Grid>가 로딩 상태를 보여주고, 준비되면 자동으로 렌더링을 시작한다.

#셀 편집 시스템 03-02 ~ 03-04

셀 편집은 Canvas 테이블의 가장 까다로운 부분이었다.

DOM 테이블에서는 <input>을 셀에 넣으면 끝이지만, Canvas에서는:

1. 더블클릭/Enter 감지
2. 해당 셀의 Canvas 좌표 계산
3. 그 위치에 DOM 오버레이 생성
4. 포커스 이동
5. 편집 완료 시 값 반영 + DOM 제거
6. Tab으로 다음 셀 이동

특히 Tab 내비게이션이 복잡했다. 편집 모드에서 Tab을 누르면 현재 셀의 편집을 완료하고, 다음 셀로 이동하면서 바로 편집 모드에 들어가야 한다. 이 과정에서 DOM 오버레이 제거 → 재생성이 한 프레임 안에 일어나야 눈에 안 보인다.

#IME 처리

한글 입력이 또 문제였다. Canvas 위의 DOM 오버레이에서 한글을 입력할 때, compositionstart/compositionend 이벤트를 제대로 처리해야 한다. 크로미움 IME 버그를 직접 고쳐본 경험이 여기서 도움이 됐다. 최소한 어떤 이벤트를 봐야 하는지, 어떤 엣지 케이스가 있는지 알고 있었으니까.

#성능 결과

최종적으로 달성한 수치:

100만 행에서 60fps 스크롤이 된다. DOM으로는 불가능한 영역이다.

#남은 과제

#Web Worker 브릿지

WASM 엔진을 Web Worker로 옮기면 메인 스레드가 완전히 자유로워진다. SharedArrayBuffer로 레이아웃 버퍼를 공유하면 가능하다. 로드맵에 있지만 아직 구현하진 않았다.

#npm 정식 배포

CI에서 npm publish 워크플로우는 만들었는데 아직 정식 릴리즈는 안 했다. API가 좀 더 안정화되면 0.1.0을 찍을 예정이다.