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

12. 툴팁 / 복사

이 문서는 @mycrm-ui/react-table에서 셀 호버 툴팁과 우클릭 복사 메뉴를 생성하거나 수정해야 하는 AI 에이전트를 위한 가이드입니다.

이 파트는 사용자가 긴 텍스트를 호버 툴팁으로 확인해야 하거나, 특정 셀 값을 우클릭 메뉴로 복사해야 하거나, 복사 이벤트를 로깅해야 할 때 사용합니다.

목적

툴팁 / 복사 파트의 목적은 아래 두 기능을 분리해서 이해하는 것입니다.

• tooltip: hover 시 내용 표시
• copyable: 우클릭 복사 메뉴

LLM은 “툴팁을 켠다”와 “복사가 가능한 셀을 지정한다”를 같은 설정으로 보지 말아야 합니다.

필수 입력

tooltip

셀 호버 시 툴팁 표시를 켭니다.

예시:

tooltip={true}

긴 텍스트가 잘리는 열에서 자주 사용합니다.

전역 copyable

복사 기능 자체를 활성화합니다.

예시:

copyable={true}

컬럼별 copyable: true

실제로 복사 가능한 열은 컬럼 단위로 지정해야 합니다.

예시:

const columns: ColumnDef<Product>[] = [
  {
    key: "name",
    label: "상품명",
    copyable: true,
    render: (row) => row.name,
  },
];

중요 규칙:

• 전역 copyable={true}만으로는 충분하지 않습니다.
• 복사 대상 열에는 컬럼별 copyable: true도 필요합니다.

onCellCopy

복사 이벤트를 수신합니다.

예시:

onCellCopy={(rowKey, colKey, value) => {
  console.log(rowKey, colKey, value);
}}

cellContextMenuItems

복사 메뉴에 사용자 정의 항목을 추가할 수 있습니다.

예시:

cellContextMenuItems={[
  {
    label: "값 로그 남기기",
    onClick: ({ rowKey, colKey, value }) => {
      console.log(rowKey, colKey, value);
    },
  },
]}

최소 동작 패턴

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

interface Product {
  id: number;
  name: string;
  sku: string;
}

const columns: ColumnDef<Product>[] = [
  {
    key: "name",
    label: "상품명",
    copyable: true,
    render: (row) => row.name,
  },
  {
    key: "sku",
    label: "SKU",
    copyable: true,
    render: (row) => row.sku,
  },
];

export default function ProductTable({ rows }: { rows: Product[] }) {
  return (
    <Table
      columns={columns}
      data={rows}
      rowKey={(row) => String(row.id)}
      tooltip={true}
      copyable={true}
      onCellCopy={(rowKey, colKey, value) => {
        console.log(rowKey, colKey, value);
      }}
    />
  );
}

LLM 판단 규칙

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

• "긴 셀 값은 호버하면 전체가 보여야 해"
• "SKU를 우클릭해서 복사하고 싶어"
• "복사 이벤트를 기록하고 싶어"
• "복사 메뉴에 커스텀 항목을 넣고 싶어"

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

1. 툴팁만 필요한지, 복사도 필요한지 판단합니다.
2. hover 가시성이 필요하면 tooltip={true}를 켭니다.
3. 복사가 필요하면 전역 copyable={true}를 켭니다.
4. 실제 복사 가능 열에만 copyable: true를 넣습니다.
5. 복사 후 동작이 필요하면 onCellCopy를 연결합니다.
6. 메뉴 커스터마이징이 필요하면 cellContextMenuItems를 추가합니다.

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

• 복사 로그 UI
• 툴팁 스타일 커스터마이징
• 컨텍스트 메뉴 스타일 커스터마이징
• 커스텀 메뉴 항목

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

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

• filter
• editing
• columnManager
• expand

자주 하는 실수

실수 1. 전역 copyable={true}만 넣고 컬럼별 copyable: true를 안 넣음

문제점:

• 어떤 열이 복사 대상인지 명확하지 않아 기대한 셀에서 복사 메뉴가 안 열릴 수 있습니다.

좋은 방식:

• 전역 옵션과 컬럼 옵션을 함께 설정합니다.

실수 2. 툴팁과 복사를 같은 기능처럼 설명

문제점:

• hover 시 표시와 우클릭 메뉴가 섞여서 요구사항 해석이 흐려집니다.

좋은 방식:

• 툴팁은 tooltip
• 복사는 copyable

로 구분합니다.

실수 3. 긴 텍스트를 잘라 놓고 툴팁을 빼먹음

문제점:

• 사용자가 전체 값을 확인할 수 없습니다.

좋은 방식:

• text-ellipsis나 whitespace-nowrap를 쓰는 열이면 tooltip 적용 여부를 먼저 검토합니다.

실수 4. 복사 이벤트를 써야 하는데 onCellCopy를 놓침

문제점:

• 로그, 토스트, 후속 액션 연결이 불가능합니다.

좋은 방식:

• 복사 후 처리 요구가 있으면 onCellCopy를 연결합니다.

LLM 안전 출력 템플릿

툴팁 / 복사 요구가 있을 때는 아래 템플릿을 우선 사용합니다.

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: "이름",
    copyable: true,
    render: (row) => row.name,
  },
];

export default function ExampleTable({ rows }: { rows: Row[] }) {
  return (
    <Table
      columns={columns}
      data={rows}
      rowKey={(row) => String(row.id)}
      tooltip={true}
      copyable={true}
    />
  );
}

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

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

• 헤더 메뉴와 함께 액션을 설계해야 함
• CSS 슬롯을 세밀하게 커스터마이징해야 함
• 문서화가 끝나고 전체 옵션 테이블과 연결해야 함