개발자 가이드 / 개발 미리보기

데이터에서 작동하는 그리드로.

코어는 상태를, 렌더러는 조작을, 앱은 저장을 관리합니다.

1. 소스에서 빌드

패키지는 npm에 게시되지 않았습니다. Node.js 22 이상과 저장소 체크아웃을 사용하세요.

git clone https://github.com/haodn-dev/acheron-grid.git
cd acheron-grid
npm ci
npm run build
npm run playground

별도 앱에서는 빌드한 패키지를 패키지 관리자로 로컬 경로에서 설치하세요.

npm install /path/to/acheron-grid/packages/core /path/to/acheron-grid/packages/canvas
헤드리스 TypeScript 코어는 상태와 명령을 관리합니다. Canvas는 셀 렌더링과 입력을 처리하며 React, Vue 또는 순수 TypeScript가 앱에 연결합니다.

2. 그리드 마운트

컨테이너 너비와 높이는 0보다 커야 합니다. 안정적인 행 ID와 명시적인 열 키를 사용하세요.

import { LocalDataSource } from '@acheron-grid/core';
import { createGrid } from '@acheron-grid/canvas';

const source = new LocalDataSource([
  { id: 1, title: 'Hello grid' }
], row => row.id);
const grid = createGrid({
  container: document.querySelector('#grid'),
  columns: [{ key: 'title', title: 'Title', editable: true }],
  dataSource: source
});
// On unmount:
grid.destroy();

3. 인터랙션 설정

열 파서로 입력을 검증하고 편집·선택·클립보드·서식 권한을 분리하세요. 셀 렌더러는 값과 서식 정보를, 옵션 렌더러는 열 키를 받습니다.

  • 편집: Enter/F2로 편집기를 열고 Enter로 체크박스 값을 전환합니다.
  • 서식: Ctrl/Cmd+B와 I는 선택한 셀의 서식을 바꾸며, 리치 텍스트 편집 중에는 선택한 텍스트에 적용됩니다.
  • 링크: 셀에 마우스를 올리거나 선택하면 안전한 링크별 바로가기가 표시됩니다.
  • 구조: 행·열 전체를 선택해 제공된 작업으로 순서 변경, 삽입, 삭제하세요.
  • 서식 있는 텍스트: HTML은 안전한 텍스트 구간으로 변환되며 Markdown은 선택 파서 어댑터를 사용합니다.

참조: Canvas 패키지 문서 에서 전체 옵션을 확인하세요. 기본 브랜치는 로컬 미리보기와 다를 수 있습니다.

편집기와 입력 검증

저장·붙여넣기 전에 열 파서로 검증하세요. 설명이 있는 오류를 던지면 초안을 유지합니다. API 갱신은 검증된 값을 받고 열 파서를 실행하지 않습니다.

columnEditors: {
  priority: { type: 'select', values: ['High', 'Medium', 'Low'] },
  tags: { type: 'multiselect', values: ['Idea', 'Design', 'Content'] },
  approved: { type: 'checkbox' }
},
choiceEditor: { placeholder: 'Find an option…', maxHeight: 220 },
multilineEditor: true,
wrapText: true,
editorOptions: { pinned: true, showLabel: 'scroll', guardNavigation: true }

생성 시 columns·데이터 소스와 함께 지정합니다. 다중 선택은 쉼표로 구분된 문자열로 저장하며 레이블에 쉼표를 넣을 수 없습니다. 위아래로 이동, Space로 전환, Enter/Apply로 저장, Escape/Cancel로 취소하세요. 옵션과 셀 렌더러의 색상을 통일하세요.

편집 및 검증 체험 ↗

검색 가능한 컨텍스트 메뉴

셀·행 번호·헤더 우클릭 또는 Shift+F10으로 엽니다. 입력으로 필터, 화살표와 Enter로 선택, Escape로 닫습니다. 선택·권한·설정에 따라 클립보드, 행·열 선택, 서식, 잠금, 고정, 크기, 삽입·삭제·이동, 병합·그룹 작업을 제공합니다. 헤더에는 정렬·필터가 있고 비활성 작업에는 이유가 표시됩니다.

검색 메뉴 체험 ↗ · 정렬 및 필터 체험 ↗

선택과 클립보드

클릭과 Shift 클릭으로 사각형을 선택하고 Ctrl/Cmd 클릭으로 범위를 추가합니다. 행 번호와 그룹 헤더는 전체 범위를 선택합니다. Shift+Space는 행, Ctrl/Cmd+Space는 열을 선택하며 Shift+F10 메뉴는 입력으로 필터링됩니다.

grid.selectRow(0);
const tsv = grid.copySelection();
grid.paste(tsv);

붙여넣기는 모든 대상·권한·파서를 검증한 뒤 원자적으로 적용하며 누락된 행을 만들지 않습니다. TSV는 값만 교환하고 내부 클립보드·구조화 API는 서식과 범위 위치를 유지할 수 있습니다. 외부 앱의 서식 보존은 보장하지 않습니다. 한도는 100,000셀과 UTF-16 단위 천만 개입니다.

선택 및 키보드 체험 ↗

값, 이벤트 및 기록

grid.updateCells([
  { rowIndex: 0, columnKey: 'title', value: 'Lorem ipsum' }
]);
grid.undo();
grid.redo();

안정적인 행 ID와 열 키를 쓰세요. LocalDataSource는 동기 원자 배치를 지원하며 사용자 소스의 다중 셀 쓰기에는 원자적 setValues가 필요합니다. 값·서식·크기·고정·구조는 제한된 기록을 공유합니다. 잠금과 자동 측정은 기록 밖에 있습니다. 재실행은 정책을 다시 검사하고 외부 변경 충돌을 거부할 수 있습니다.

사용: onEvent 로 확정된 도메인 이벤트를 관찰하세요: cell:change 및 structure:change. 알림은 확정된 변경을 되돌리지 않습니다. 소스 직접 쓰기는 기록을 우회하며 저장은 앱의 책임입니다.

검색, 정렬 및 필터

grid.openSearch();
grid.setView({
  sort: { columnKey: 'title', direction: 'asc' },
  filters: [{ columnKey: 'title', operator: 'contains', query: 'Lorem' }]
});
grid.setView({});

검색은 표시 텍스트를 강조합니다. 로컬 뷰는 한 열을 정렬하고 AND로 필터를 결합하며 contains, equals, not-empty, empty를 지원합니다. onViewChange 사용 시 viewMode: 'core'도 지정해 상태를 보존하세요. 공개 행 좌표는 표시 순서이고 권한·선택 외 이벤트는 소스 좌표와 안정 ID를 사용합니다.

구조 작업 전에 뷰를 초기화하고 정렬·필터 전에 병합·그룹을 해제하세요. 메모리 필터·정렬 비용은 소스 크기에 비례합니다.

검색·정렬·필터 체험 ↗

그룹 헤더, 고정 및 크기 변경

headerGroups: [{ title: 'Availability', children: [
  { title: 'Channels', children: ['online', 'onsite'] },
  { title: 'Delivery', children: ['shipping'] }
] }],
headerHeight: 28,
autoRowHeight: true,
wrapText: true

열은 평평하게 정의하고 그룹의 끝 열은 중복 없이 연속된 열 순서를 유지하세요. headerHeight는 각 헤더 행 높이이며 하위 열을 선택하면 상위 헤더도 강조됩니다.

grid.setFrozen(1, 1);
grid.setColumnWidth(1, 240);
grid.setRowHeight(0, 64);

고정 개수는 헤더·행 번호를 제외합니다. 안내선을 보며 크기를 변경하고 놓으면 적용합니다. 자동 맞춤은 표시된 내용, 자동 행 높이는 표시 행의 전체 열을 측정합니다. 수동 크기가 우선이며 큰 고정 영역은 화면을 차지할 수 있습니다.

헤더·고정·크기 변경 체험 ↗

구조, 병합 및 행 그룹

onReorder로 드래그를 활성화하고 공개 API로 이동을 적용하세요. beforeIndex는 제거 전 삽입 경계입니다. 호스트는 onRowChange로 행 ID·기본값을 만들며 allowColumnChanges는 열 생성·삭제 메뉴를 활성화합니다.

onReorder: request => {
  if (request.axis === 'row') grid.moveRows(request.indices, request.beforeIndex);
  else grid.moveColumns(request.indices, request.beforeIndex);
}

콜백은 마운트 후 grid가 있을 때 실행됩니다. canChangeStructure는 명령과 기록 재실행에도 적용됩니다. 그룹 열은 연속해야 합니다.

grid.mergeCells({ startRow: 2, endRow: 3, startColumn: 1, endColumn: 2 });
const groupId = grid.groupRows(3, 6);
grid.setGroupCollapsed(groupId, true);
grid.setGroupCollapsed(groupId, false);
grid.ungroupRows(groupId);

범위는 끝점을 포함합니다. 병합은 원래 값을 유지하고 행 그룹은 집계가 아닌 수동 묶음입니다. 호환되지 않는 구조 변경 전에 그룹을 펼치고 관련 셀 병합을 해제하세요.

행·열 작업 체험 ↗ · 병합 및 그룹 체험 ↗

서식 있는 텍스트, 이미지 및 안전한 링크

import { markdownToHtml } from '@acheron-grid/markdown';

// createGrid options:
richTextColumns: { notes: 'markdown', description: 'html' },
markdownToHtml,
imageColumns: ['avatar']

Markdown 어댑터는 선택 사항이며 core/Canvas는 파서에 의존하지 않습니다. 사용자는 서식을 보고 호스트는 소스 문자열을 저장합니다. HTML은 밑줄을 지원하지만 Markdown에 새 밑줄 문법을 추가하지 않습니다. Ctrl/Cmd+B·I는 편집 중 선택 텍스트 또는 선택 셀에 적용됩니다.

Canvas는 제한된 텍스트 구간만 그리고 HTML 마운트나 핸들러 실행을 하지 않습니다. 다른 DOM에 저장 HTML을 넣기 위한 범용 정화기는 아닙니다. 표시 이미지는 익명 CORS로 요청하며 업로드·자르기는 없습니다. 링크 셀에 마우스나 포커스를 두면 안전한 URL 바로가기가 표시됩니다.

서식 있는 텍스트·링크 체험 ↗

권한, 잠금 및 사용자 설정

resolveCellPermission: cell => cell.rowId === 'protected'
  ? { writable: false }
  : undefined,
permissions: { formatting: false }

선택·복사·붙여넣기·편집·쓰기·서식은 독립 권한입니다. 명시적 false는 더 구체적인 범위에서도 거부를 유지합니다. 읽기 전용 행도 선택·복사할 수 있습니다. 동적 정책 변경 후 grid.render()로 갱신하며 저장 시 정책을 재검사합니다.

grid.setLocked({ scope: 'row', rowIndex: 0 }, true);
grid.format([{ scope: 'column', columnIndex: 1 }], { background: '#fff0dd' });
grid.setTheme({ selectionColor: '#d44b21', iconColor: '#334155' });

잠금은 셀·행·열·표에 적용됩니다. 셀 잠금 해제는 행·표 잠금을 해제하지 않습니다. 고정은 표시만 유지하고 편집을 금지하지 않습니다. 테마 갱신은 마운트를 유지하며 renderCell/createEditor로 표시를 바꿉니다. 지원하는 서식 필드를 존중하고 클라이언트 정책을 서버 권한 검사 대신 쓰지 마세요.

서식 및 권한 체험 ↗

문제 해결

  • 빈 그리드: 컨테이너 크기, 소스 행 수, 열 키와 브라우저 콘솔을 확인하세요.
  • 편집 불가: editable, 파서, setter, 권한과 잠금을 확인하세요.
  • Markdown 거부: 동기 markdownToHtml 콜백을 제공하세요.
  • 이미지 표시 불가: URL, CORS와 서버 응답을 확인하세요.
  • 이동·뷰 변경 거부: 활성 초안, 뷰, 그룹, 병합과 호스트 정책을 확인하세요.
  • 실행 취소 없음: 소스 직접 수정과 자동 측정은 사용자 기록에 포함되지 않습니다.

호스트 해제 시 반드시 그리드를 정리하세요. 참조: 전체 Markdown 실용 가이드 와 패키지 계약에서 자세한 제한을 확인하세요.

React와 Vue

패키지 @acheron-grid/react 및 @acheron-grid/vue 는 Canvas 마운트·해제, 타입 지정 refs, 코어 이벤트 전달을 관리합니다. options를 안정적으로 유지하고 테마·뷰·고정 영역은 재마운트 없이 props로 갱신하세요.

읽기: React 및 Vue Markdown 예제 에서 전체 컴포넌트, peer 버전, 수명 주기 계약을 확인하세요. SSR에서는 빈 컨테이너를 렌더링하며 프레임워크는 코어 밖에 있습니다.

4. AI 도우미와 읽기

먼저 공개 문서 색인, 다음으로 AI 통합 참고 사항. Markdown에는 구체적 예제와 구현된 제한이 있습니다. 인증 정보나 내부 계획은 공개하지 않습니다.

선택 MCP 어댑터는 문서와 호스트 승인 읽기·수정 도구를 제공합니다. 참조: MCP 참조 에서 stdio 설정과 제한을 확인하세요. 브라우저 데모는 자동 연결되지 않습니다.

다섯 패키지 및 AI 문서 살펴보기 ↗

API 참조와 상세 예제

이 가이드는 일반적인 흐름을 다룹니다. 전체 옵션·메서드, 기본값, 콜백 데이터와 예외는 패키지 문서에서 확인하세요.

검색 가능한 자동 생성 API 참조와 모든 렌더러·편집기 실행 예제는 아직 없습니다. 저장소 문서와 로컬 버전이 다를 수 있습니다.

현재 제한 사항

실험적 개발 미리보기입니다. 원격 데이터 소스, 협업, 수식, 자동 MCP 브리지는 없습니다. 변경은 현재 세션에만 적용되며 메모리 필터링 비용은 데이터 크기에 비례합니다.

Hao Duong의 MIT 라이선스입니다. 프로덕션 성능이나 접근성 인증을 주장하지 않습니다.