開発ガイド / 開発プレビュー

行から動くグリッドへ。

状態はコア。操作はレンダラー。保存はアプリ。

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 セルと 1,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({});

検索は表示テキストを強調。ローカルビューは 1 列を並べ替え、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 向けの汎用サニタイザーではありません。表示画像は匿名 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 のマウント・解除、型付き ref、イベント転送を管理します。options を安定させ、テーマ・ビュー・固定領域は再マウントせず props で更新します。

参照： React・Vue の Markdown 例 で完全なコンポーネント、peer バージョン、ライフサイクルを確認。SSR では空のコンテナーを描画し、フレームワークはコアの外に置きます。

4. AI と一緒に読む

まず 公開資料の目次、続いて AI 導入の注意点。Markdown に具体例と実装済みの制限があります。認証情報や内部計画は公開しません。

任意の MCP アダプターが資料とホスト承認の読み取り・更新ツールを提供。参照： MCP リファレンス で stdio 設定と制限を確認してください。ブラウザーデモには自動接続しません。

5 パッケージと AI の資料を見る ↗

API 資料と詳細な例

ここでは一般的な手順を説明します。全オプション・メソッド、既定値、コールバック、境界ケースはパッケージ資料をご覧ください。

検索できる自動生成 API 資料や、全レンダラー・エディターの実行例は未提供です。資料とローカル版のリビジョンが異なる場合があります。

現在の制限

実験的な開発プレビューです。リモートデータソース、共同編集、数式、自動 MCP ブリッジは未提供。変更は現在のセッションのみ。仮想化してもメモリー内絞り込みはデータ量に依存します。

MIT ライセンス、Hao Duong。商用環境の性能保証やアクセシビリティ認証はありません。