@mycrm-ui/react-table LLM 가이드

8. 가상 스크롤

이 문서는 @mycrm-ui/react-table에서 대용량 데이터용 가상 스크롤과 무한 로딩을 구성하는 코드를 생성하거나 수정해야 하는 AI 에이전트를 위한 가이드입니다.

이 파트는 사용자가 많은 행을 성능 저하 없이 렌더링하고 싶어 하거나, 스크롤 끝에서 추가 데이터를 불러오는 무한 스크롤이 필요할 때 사용합니다.

목적

가상 스크롤 파트의 목적은 아래 조건들을 함께 만족시키는 것입니다.

• scroll.virtual: true
• 고정된 rowHeight
• 실제 스크롤 컨테이너 높이
• 무한 로딩용 onLoadMore, hasMore, loadingMore

LLM은 가상 스크롤을 단순 옵션 하나로 보지 말고, 레이아웃 조건과 로딩 상태까지 함께 맞춰야 합니다.

필수 입력

scroll.virtual

가상 스크롤을 활성화하려면 virtual: true를 설정합니다.

예시:

scroll={{
  virtual: true,
}}

scroll.rowHeight

가상 스크롤에서는 각 행의 높이를 고정값으로 알려줘야 합니다.

예시:

scroll={{
  virtual: true,
  rowHeight: 48,
}}

중요 규칙:

• rowHeight는 가상 스크롤 사용 시 필수입니다.

classNames.wrap

실제 스크롤이 일어날 컨테이너 높이를 지정해야 합니다.

예시:

classNames={{
  wrap: "h-[380px] overflow-y-auto",
}}

중요 규칙:

• 고정 높이와 overflow-y-auto 또는 overflow-y-scroll이 필요합니다.

scroll.stickyHeader

스크롤 중 헤더 고정이 필요하면 설정합니다.

예시:

scroll={{
  virtual: true,
  rowHeight: 48,
  stickyHeader: true,
}}

scroll.onLoadMore

스크롤 끝 도달 시 다음 데이터를 불러옵니다.

예시:

scroll={{
  virtual: true,
  rowHeight: 48,
  onLoadMore: handleLoadMore,
  hasMore,
  loadingMore,
}}

무한 로딩에서는 보통 아래 상태를 함께 둡니다.

• hasMore
• loadingMore

최소 동작 패턴

import { useState } from "react";
import { Table } from "@mycrm-ui/react-table";
import type { ColumnDef } from "@mycrm-ui/react-table";

interface Row {
  id: number;
  name: string;
}

const columns: ColumnDef<Row>[] = [
  { key: "name", label: "이름", render: (row) => row.name },
];

export default function ExampleTable({ initialRows }: { initialRows: Row[] }) {
  const [rows, setRows] = useState(initialRows);
  const [hasMore, setHasMore] = useState(true);
  const [loadingMore, setLoadingMore] = useState(false);

  const handleLoadMore = async () => {
    if (loadingMore || !hasMore) return;
    setLoadingMore(true);
    // 추가 데이터 로드
    setLoadingMore(false);
  };

  return (
    <Table
      columns={columns}
      data={rows}
      rowKey={(row) => String(row.id)}
      scroll={{
        virtual: true,
        rowHeight: 48,
        stickyHeader: true,
        onLoadMore: handleLoadMore,
        hasMore,
        loadingMore,
      }}
      classNames={{
        wrap: "h-[380px] overflow-y-auto",
      }}
    />
  );
}

LLM 판단 규칙

사용자 요청이 아래 의미에 가깝다면 이 가이드를 사용합니다.

• "행이 많아도 부드럽게 스크롤되게 해줘"
• "대용량 테이블이라 성능 최적화가 필요해"
• "스크롤 끝에서 다음 데이터를 불러오고 싶어"
• "헤더는 고정하고 본문만 스크롤되게 해줘"

이 경우 LLM은 아래 순서로 처리합니다.

1. 행 수가 많아 가상 스크롤이 필요한지 판단합니다.
2. scroll.virtual: true와 rowHeight를 설정합니다.
3. classNames.wrap에 고정 높이와 overflow-y-*를 추가합니다.
4. 헤더 고정이 필요하면 stickyHeader를 켭니다.
5. 무한 로딩이 필요하면 onLoadMore, hasMore, loadingMore를 연결합니다.
6. 중복 로딩 방지 조건을 handleLoadMore 안에 넣습니다.

이 파트에서 추가해도 되는 것

• overscan
• renderLoadingMore
• 초기화 버튼
• 현재 로드된 행 수 표시

이 파트에서 추가하지 말아야 하는 것

사용자가 명시적으로 요구하지 않았다면 아래 기능은 함께 넣지 않습니다.

• filter
• editing
• rowActions
• columnManager
• expand

자주 하는 실수

실수 1. virtual: true만 넣고 rowHeight를 빼먹음

문제점:

• 가상 스크롤 계산이 깨지거나 의도와 다르게 동작할 수 있습니다.

좋은 방식:

• 가상 스크롤 사용 시 항상 rowHeight를 함께 지정합니다.

실수 2. classNames.wrap에 높이나 스크롤 설정이 없음

문제점:

• 실제 스크롤 컨테이너가 생기지 않아 가상 스크롤이 의미 있게 동작하지 않습니다.

좋은 방식:

• h-[...]와 overflow-y-auto 또는 overflow-y-scroll을 함께 설정합니다.

실수 3. onLoadMore에서 중복 호출 방지 조건이 없음

문제점:

• 스크롤 끝에서 연속 호출이 발생해 중복 요청이 생길 수 있습니다.

좋은 방식:

• if (loadingMore || !hasMore) return; 같은 가드를 둡니다.

실수 4. hasMore 갱신을 빼먹음

문제점:

• 더 불러올 데이터가 없는데도 계속 로딩이 시도될 수 있습니다.

좋은 방식:

• 새 데이터 수를 기준으로 hasMore를 갱신합니다.

LLM 안전 출력 템플릿

가상 스크롤 요구가 있을 때는 아래 템플릿을 우선 사용합니다.

import { useState } from "react";
import { Table } from "@mycrm-ui/react-table";
import type { ColumnDef } from "@mycrm-ui/react-table";

interface Row {
  id: number;
  name: string;
}

const columns: ColumnDef<Row>[] = [
  { key: "name", label: "이름", render: (row) => row.name },
];

export default function ExampleTable({ rows }: { rows: Row[] }) {
  const [data, setData] = useState(rows);
  const [hasMore, setHasMore] = useState(true);
  const [loadingMore, setLoadingMore] = useState(false);

  const handleLoadMore = async () => {
    if (loadingMore || !hasMore) return;
    setLoadingMore(true);
    setLoadingMore(false);
  };

  return (
    <Table
      columns={columns}
      data={data}
      rowKey={(row) => String(row.id)}
      scroll={{
        virtual: true,
        rowHeight: 48,
        onLoadMore: handleLoadMore,
        hasMore,
        loadingMore,
      }}
      classNames={{
        wrap: "h-[380px] overflow-y-auto",
      }}
    />
  );
}

다음 가이드로 넘어가야 하는 조건

아래 요구가 나오면 다음 파트로 넘어갑니다.

• 컬럼 숨김, 고정, 순서 변경이 필요함
• 확장 행과 가상 스크롤을 같이 써야 함
• 스크롤 안에서 편집, 선택, 툴팁까지 같이 다뤄야 함
• 서버 페이지네이션과 가상 스크롤 전략을 함께 설계해야 함