Core CSV · JSON 내보내기

comins-table@0.2.2React

0.2.0: 이 페이지의 타입과 helper는 루트 comins-table의 React 상태 계약입니다. 중립 /core는 별도 타입 계약을 사용합니다. 마이그레이션 가이드에서 import 경로와 셀 정책 차이를 확인합니다.

전달한 행과 export 컬럼 정의를 문자열로 변환합니다. 테이블의 선택·페이지·전체 서버 데이터를 자동으로 조회하지 않으며 다운로드도 호출하지 않습니다.

실행 예제

미리보기

코드

TableCoreDemo.tsx

import { useMemo, useState } from 'react';
import { CominsTable, createCominsTableState, exportCominsRowsToCsv, exportCominsRowsToJson, getCominsPageRows, selectRows, setCominsSortModel, updateCominsRows, addCominsRows, type CominsTableColumn, type CominsExportRowsOptions } from 'comins-table';
import 'comins-table/styles.css';

type Row = { id: string; name: string; amount: number };
const rows: Row[] = [{ id: 'a', name: 'Alpha', amount: 30 }, { id: 'b', name: 'Beta, quoted', amount: 10 }, { id: 'c', name: 'Gamma', amount: 20 }];

export default function TableCoreDemo({ lang = 'ko' }: { lang?: string }) {
  const ko = lang === 'ko';
  const columns = useMemo<CominsTableColumn<Row>[]>(() => [
    { field: 'id', label: 'ID', width: 100 },
    { field: 'name', label: ko ? '이름' : 'Name', width: 240 },
    { field: 'amount', label: ko ? '수량' : 'Amount', width: 130, sort: true },
  ], [ko]);
  const makeState = () => createCominsTableState({ rows, columns, getRowId: (row: Row) => row.id, pagination: { pageSize: 20 } });
  const [state, setState] = useState(makeState);
  const [format, setFormat] = useState<'csv' | 'json'>('csv');
  const [formatted, setFormatted] = useState(false);
  // Core derives row order. The React Table renders that result through its own props.
  const displayColumns = useMemo(() => columns.map(column => ({ ...column, sort: false })), [columns]);
  const displayedRows = getCominsPageRows(state);
  const options: CominsExportRowsOptions<Row> = {
    rows: displayedRows,
    columns: [
      { id: 'id', label: 'ID', value: row => row.id },
      { id: 'name', label: ko ? '이름' : 'Name', value: row => row.name },
      { id: 'amount', label: ko ? '수량' : 'Amount', value: row => row.amount, format: row => `${row.amount} ${ko ? '개' : 'units'}` },
    ],
    valueSource: formatted ? 'formatted' : 'raw',
  };
  const output = format === 'csv' ? exportCominsRowsToCsv(options) : exportCominsRowsToJson(options);
  return <div className="demo" data-demo="table-core">
    <div className="demo-toolbar">
      <button onClick={() => setState(value => setCominsSortModel(value, [{ columnId: 'amount', direction: 'asc' }]))}>{ko ? '수량 오름차순' : 'Sort amount ascending'}</button>
      <button onClick={() => setState(value => selectRows(value, ['a']))}>{ko ? 'ID a 선택' : 'Select ID a'}</button>
      <button onClick={() => setState(value => updateCominsRows(value, [{ id: 'a', patch: row => ({ ...row, amount: row.amount + 1 }) }]))}>{ko ? 'a 수량 +1' : 'a amount +1'}</button>
      <button disabled={state.rows.length > 3} onClick={() => setState(value => addCominsRows(value, [{ id: 'd', name: 'Delta', amount: 15 }]))}>{ko ? '행 추가' : 'Add row'}</button>
      <button onClick={() => { setState(makeState()); setFormat('csv'); setFormatted(false); }}>{ko ? '초기화' : 'Reset'}</button>
    </div>
    <div className="table-viewport">
      <CominsTable data={displayedRows} columns={displayColumns} getRowId={row => row.id} rowSelectionOnClick={false} rowProps={{ draggable: false }} />
    </div>
    <p className="demo-status" data-core-state>{ko ? '기준 순서' : 'Source order'}: {state.rowIds.join(', ')} · {ko ? '표시 순서' : 'Display order'}: {displayedRows.map(row => row.id).join(', ')} · {ko ? 'Core 선택' : 'Core selection'}: {state.selection.rowIds.join(', ') || '—'}</p>
    <div className="demo-toolbar" data-export-format style={{ marginTop: 16 }}>
      <button aria-pressed={format === 'csv'} onClick={() => setFormat('csv')}>CSV</button>
      <button aria-pressed={format === 'json'} onClick={() => setFormat('json')}>JSON</button>
      <button aria-pressed={formatted} onClick={() => setFormatted(value => !value)}>{ko ? '표시값 사용' : 'Use formatted values'}: {formatted ? 'ON' : 'OFF'}</button>
    </div>
    <pre data-core-export aria-label={ko ? '내보내기 결과' : 'Export result'}>{output}</pre>
  </div>;
}

exportCominsRowsToCsv

export declare function exportCominsRowsToCsv<TData>({ columnOrder, columns, headerOverrides, rows, metadata, valueSource, }: CominsExportRowsOptions<TData>): string;

헤더 1행과 데이터 행을 개행으로 연결합니다. 쉼표·따옴표·CR/LF가 포함된 값은 CSV 인용 규칙으로 처리합니다. null/undefined는 빈 칸, 객체는 JSON 문자열입니다. 헤더 우선순위는 headerOverrides[id] → label → id → 빈 문자열입니다.

exportCominsRowsToJson

export declare function exportCominsRowsToJson<TData>({ columnOrder, columns, headerOverrides, rows, metadata, valueSource, }: CominsExportRowsOptions<TData>): string;

CSV와 같은 헤더 결정값을 객체 key로 사용하고 2칸 들여쓴 JSON 배열 문자열을 반환합니다. 같은 헤더 key는 뒤 컬럼이 덮으므로 고유한 헤더를 지정합니다. 값은 JSON.stringify 규칙을 따르며 순환 참조·bigint 등은 예외가 날 수 있습니다.

CominsExportFormat

export type CominsExportFormat = "csv" | "json";

csv 또는 json 형식 토큰입니다. 각각의 export 함수를 선택할 때 사용할 수 있습니다.

CominsExportValueSource

export type CominsExportValueSource = "formatted" | "raw";

기본 raw는 value를 사용합니다. formatted는 format이 있으면 호출하고, 없으면 value를 사용합니다.

CominsExportColumn

export type CominsExportColumn<TData> = {
    format?: (row: TData, rowIndex: number) => unknown;
    id?: string;
    label?: string;
    value: (row: TData, rowIndex: number) => unknown;
};

속성	동작·기본값
format	선택. formatted 모드에서 사용하는 값 변환.
id	선택. columnOrder/headerOverrides에서 참조할 ID.
label	선택 헤더 문자열.
value	필수. 행과 전달된 배열의 rowIndex에서 원시 값을 계산합니다.

CominsExportRowsOptions

export type CominsExportRowsOptions<TData> = {
    columnOrder?: string[];
    columns: Array<CominsExportColumn<TData>>;
    headerOverrides?: Record<string, string>;
    rows: readonly TData[];
    metadata?: CominsExportMetadata<TData>;
    valueSource?: CominsExportValueSource;
};

속성	동작·기본값
columnOrder	비어 있지 않으면 나열한 ID만 그 순서로 내보냅니다. 생략/빈 배열이면 columns 전체 순서입니다.
columns	필수 export 컬럼 정의. React 표시 컬럼 정의와는 별도입니다.
headerOverrides	컬럼 ID별 헤더 재정의. JSON key에도 적용합니다.
rows	필수 내보낼 행 배열. 호출자가 범위를 결정합니다.
metadata	선택 관리 열 getter입니다. 아래 계약을 참조합니다.
valueSource	raw(기본) 또는 formatted.

관련 문서

• Core 상태 모델
• Core 행 조회·변경

CSV Import와 구조 옵션 생성 함수는 React·DOM 없이 comins-table/core에서 같은 계약으로 사용합니다.

가져오기·내보내기 가이드

importCominsRowsFromCsv

export declare function importCominsRowsFromCsv<TData>({ text, mapRow, hasHeader, maxCharacters, maxCells, }: CominsCsvImportOptions<TData>): TData[];

전체 CSV의 구문과 열 수를 검증한 뒤 mapRow로 일반 행 배열을 생성합니다. 구문 오류는 SyntaxError, 제한값 오류·한도 초과는 RangeError를 발생시킵니다. 매핑 오류는 그대로 전달하고 일부 행만 반환하지 않습니다. 콜백 부수효과는 되돌리지 않으므로 순수한 매핑을 사용합니다. 파일 읽기·ID 생성·Table 갱신·Tree·Group 복원은 수행하지 않습니다.

CominsCsvImportRow

export type CominsCsvImportRow = {
    cells: readonly string[];
    headers: readonly string[] | null;
    rowIndex: number;
};

읽기 전용 매퍼 입력입니다. 헤더로 객체 속성이나 필드 경로를 자동 생성하지 않으며 중복 헤더를 그대로 보존합니다.

속성	동작·기본값
cells	현재 레코드의 읽기 전용 원문 셀 배열입니다.
headers	기본 첫 레코드이며 hasHeader=false이면 null입니다.
rowIndex	헤더를 제외한 데이터 행 기준 0부터 시작합니다.

CominsCsvImportOptions

export type CominsCsvImportOptions<TData> = {
    text: string;
    mapRow: (row: CominsCsvImportRow) => TData;
    hasHeader?: boolean;
    maxCharacters?: number;
    maxCells?: number;
};

CRLF·LF·CR 레코드 구분과 이중 따옴표 이스케이프를 지원합니다. 따옴표 안의 줄바꿈·공백·앞자리 0·수식 문자열을 보존합니다. 초기 BOM과 마지막 레코드 구분자를 제외합니다. 빈 입력과 헤더만 있는 입력은 빈 배열을 반환합니다. 실제 빈 레코드는 유지하고 열 수가 다르면 거부합니다. 동기 메모리 처리이며 수식·HTML용 값을 정제하지 않습니다.

속성	동작·기본값
text	필수 CSV 문자열입니다. 파일 바이트는 호출자가 디코딩합니다.
mapRow	필수 순수 행 매퍼입니다. 헤더·값·업무 규칙을 직접 검증합니다.
hasHeader	기본 true입니다. false이면 첫 레코드부터 데이터입니다.
maxCharacters	기본 1,000,000입니다. BOM 포함 UTF-16 코드 단위이며 양의 안전한 정수만 허용합니다.
maxCells	기본 100,000입니다. 헤더 포함 셀 수이며 양의 안전한 정수만 허용합니다.

CominsExportMetadata

export type CominsExportMetadata<TData> = {
    __rowId?: (row: TData, rowIndex: number) => CominsRowId;
    __parentId?: (row: TData, rowIndex: number) => CominsRowId | null;
    __depth?: (row: TData, rowIndex: number) => number;
    __groupId?: (row: TData, rowIndex: number) => CominsRowId | null;
};

활성 관리 열을 업무 열 뒤에 __rowId·__parentId·__depth·__groupId 순서로 추가합니다. 원본 행에 속성을 주입하지 않습니다. 관리 헤더와 업무 헤더가 충돌하면 오류를 발생시킵니다. columnOrder·headerOverrides·valueSource는 업무 열에만 적용합니다. JSON은 null과 숫자·문자열 ID 타입을 보존하며 CSV는 null을 빈 셀로 출력합니다.

속성	동작·기본값
__rowId	행 ID getter입니다.
__parentId	부모 ID getter입니다. 루트는 null입니다.
__depth	깊이 getter입니다. 루트는 0입니다.
__groupId	그룹 ID getter입니다.

CominsExportTreeOptions

export type CominsExportTreeOptions<TData> = Omit<CominsExportRowsOptions<TData>, "rows" | "metadata"> & {
    nodes: readonly import("./tree").CominsTreeNode<TData>[];
    getRowId: (row: TData, sourceIndex: number) => CominsRowId;
};

전체 입력 Tree를 내보내는 옵션입니다. 업무 열 옵션을 상속하며 UI의 접힘·필터·선택 상태를 자동으로 읽지 않습니다.

속성	동작·기본값
nodes	필수 원본 Tree 노드 배열입니다.
getRowId	필수 행 ID getter입니다. Tree는 전위 순서, Group은 원래 입력 인덱스를 전달합니다.

CominsExportGroupedOptions

export type CominsExportGroupedOptions<TData, TGroup> = Omit<CominsExportRowsOptions<TData>, "metadata"> & {
    groups: readonly TGroup[];
    getGroupId: (group: TGroup) => CominsRowId;
    getRowGroupId: (row: TData, sourceIndex: number) => CominsRowId;
    getRowId: (row: TData, sourceIndex: number) => CominsRowId;
};

단일 계층 Group의 소속을 내보내는 옵션입니다. 내보낼 rows와 groups는 호출자가 지정합니다.

속성	동작·기본값
groups	필수 그룹 배열입니다. 그룹 출력 순서를 결정합니다.
getGroupId	필수 그룹 ID getter입니다.
getRowGroupId	필수 행 소속 그룹 ID getter입니다.
getRowId	필수 행 ID getter입니다. Tree는 전위 순서, Group은 원래 입력 인덱스를 전달합니다.

createCominsTreeExportOptions

export declare function createCominsTreeExportOptions<TData>({ nodes, getRowId, ...options }: CominsExportTreeOptions<TData>): CominsExportRowsOptions<TData>;

접힌 자식까지 포함해 전위 순회하고 __rowId·__parentId·__depth를 연결합니다. 루트의 부모는 null, 깊이는 0입니다. getRowId 인덱스는 전체 전위 순서를 따릅니다. 중복 ID와 순환 참조를 거부합니다. 원본 행 참조를 유지한 CSV·JSON 공통 옵션을 반환합니다. 반환 rows를 별도로 교체·재정렬하지 않으며 데이터나 구조 변경 후 옵션을 다시 생성합니다.

createCominsGroupedExportOptions

export declare function createCominsGroupedExportOptions<TData, TGroup>({ rows, groups, getGroupId, getRowGroupId, getRowId, ...options }: CominsExportGroupedOptions<TData, TGroup>): CominsExportRowsOptions<TData>;

groups 순서와 그룹 내 원래 입력 행 순서를 따르며 __rowId·__groupId를 연결합니다. ID getter는 원래 입력 인덱스, Column value·format은 최종 Export 인덱스를 받습니다. 중복 그룹·행 ID와 미등록 그룹 참조를 거부합니다. 빈 그룹의 가상 행이나 제목·집계 행을 추가하지 않습니다. 반환 rows와 옵션을 함께 사용하고 데이터 변경 후 다시 생성합니다.