@lembryo/voxsheet

概要

VoxSheet は DOM ベースの仮想スクロールにより、行数が膨大でも表示中のセルだけを描画します。データ取得とドメイン状態（ソート・フィルタ・検索）はホストが所有し、ビューポート・選択・編集バッファ・キーボードはグリッドが所有します。

• Transport 非依存 — 取得手段は fetchRows に委ねるため、REST / GraphQL / ローカル配列どれでも可。
• TypeScript ファースト — 公開 API はすべて型付き。
• ピア依存モデル — react / react-dom は peer dependency。
• 外部 CSS フレームワーク不使用 — --vox-* 変数と vox- クラスで完結。

なぜ voxsheet？

voxsheet の特徴は、「無償（MIT）で Excel 風の編集体験」と「サーバ駆動を前提にした設計」を最初から両立している点です。

• 無償で Excel 風編集 — オートフィル（フィルハンドル）・複数レンジ選択・コピー＆ペースト・列リサイズを標準装備。
• サーバ駆動が前提 — ソート・フィルタ・検索・ページングを fetchRows 経由でバックエンドに委譲。巨大データでも可視範囲だけを取得します。
• React ネイティブ / DOM ベース — hooks・controlled props・JSX セル。Canvas 実装と異なり、通常の DOM で拡張・検査・アクセシビリティを扱えます。
• TypeScript ファースト・外部 CSS 不使用・peer 依存 — 既存のビルドやテーマに溶け込みやすい。

競合との違い

voxsheet が標準提供する機能には、他の主要グリッドでは有償プランや別ライセンスが必要なものがあります（下表は代表例。各製品のライセンスは変わり得るため、採用前に最新の条件を確認してください）。

インストール

npm install @lembryo/voxsheet

react / react-dom（v18 以上）は peer dependency です。スタイルシートのインポートも忘れずに行ってください。

import { VoxSheet } from "@lembryo/voxsheet"
import "@lembryo/voxsheet/styles.css"

クイックスタート

最小構成の例です。columns・totalRows・fetchRows の 3 つが必須です。

import { useCallback, useState } from "react"
import { VoxSheet } from "@lembryo/voxsheet"
import type { Column, FetchResult, Query, SortSpec } from "@lembryo/voxsheet"
import "@lembryo/voxsheet/styles.css"

const columns: Column[] = [
    { name: "id", type: "number" },
    { name: "name", type: "string" },
    {
        name: "salary",
        type: "number",
        format: { kind: "number", options: { style: "currency", currency: "USD" } },
    },
    { name: "joinedAt", type: "date" },
]

export function App() {
    const [sort, setSort] = useState<SortSpec[]>([])
    const [total, setTotal] = useState(0)

    // グリッドは Query（offset/limit + controlled な sort/filters/search）と
    // 陳腐化リクエストを中断するための AbortSignal を渡してくる。
    const fetchRows = useCallback(
        async (query: Query, signal: AbortSignal): Promise<FetchResult> => {
            const res = await fetch("/api/rows", {
                method: "POST",
                headers: { "Content-Type": "application/json" },
                body: JSON.stringify(query),
                signal,
            })
            const json: FetchResult = await res.json()
            if (typeof json.total === "number") setTotal(json.total)
            return json
        },
        [],
    )

    return (
        <VoxSheet
            columns={columns}
            totalRows={total}
            fetchRows={fetchRows}
            sort={sort}
            onSortChange={setSort}
        />
    )
}

コアコンセプト

VoxSheet は controlled かつ transport 非依存です。責務は次のように分かれます。

ソートやフィルタの「状態」はホストが useState 等で持ち、グリッドはユーザー操作をコールバックで通知するだけです。状態が変わると fetchRows が新しい Query で再度呼ばれます。

データ契約

グリッドとホストの間で受け渡す型は次のとおりです。これらが voxsheet を使う上での中心になります。

CellValue

セルの値。JSON シリアライズ可能な型に限定されます。

type CellValue = string | number | boolean | null

• 日付は ISO 8601 文字列（推奨）または epoch ミリ秒で運び、列 type: "date" で解釈します。
• null は SQL の NULL を表し、空文字 "" と区別されます。

Query

グリッドが fetchRows に渡す取得条件。offset / limit はグリッドが決め、sort / filters / search はホストが渡した controlled 値がそのまま入ります。

type Query = {
    offset: number
    limit: number
    sort: SortSpec[]      // 多列。配列順 = 優先順位
    filters: FilterSpec[] // AND 結合
    search?: string
}

FetchResult

fetchRows が返す値。data[i][j] は i 行目・j 列目で、列順は columns に揃えます。

fetchRows

行データを範囲指定で取得する関数。第 2 引数の signal で陳腐化した取得を中断できます。

type FetchRowsFn = (query: Query, signal: AbortSignal) => Promise<FetchResult>

列定義

Column

列メタデータ。type が描画・編集・比較・オートフィルを駆動します。表示/非表示は配列から除外して表現します（controlled）。

表示整形 format

Intl のオプション、または任意の関数で値を文字列化します。解決順は 関数 > kind 別既定 です。

type ColumnFormat =
    | { kind: "number"; options: Intl.NumberFormatOptions }
    | { kind: "date"; options: Intl.DateTimeFormatOptions }
    | ((value: CellValue, ctx: { column: Column; row: number }) => string)

// 通貨表示
{ name: "salary", type: "number",
  format: { kind: "number", options: { style: "currency", currency: "JPY" } } }

// 関数で完全カスタム
{ name: "status", format: (v) => (v === 1 ? "有効" : "無効") }

編集とバリデーション

editable で列・行単位の編集可否を、validate で入力検証を行います。

{
    name: "email",
    type: "string",
    editable: ({ row }) => row > 0,        // 行ごとに可否
    validate: (value) =>
        typeof value === "string" && value.includes("@")
            ? true
            : "メールアドレスの形式が不正です",  // 文字列を返すと却下＋メッセージ
}

Props リファレンス

VoxSheetProps をカテゴリ別に示します。

データ

レイアウト・表示

振る舞い（controlled ドメイン状態）

状態 UI・拡張

イベント（コールバック）

ボタンや操作系の affordance は、対応するコールバックが未指定だと非表示・無効になります。

ソート

ソートは controlled です。グリッドはヘッダクリックで none → asc → desc をトグルし onSortChange で通知、ホストが sort を更新します。配列の順序が多列ソートの優先順位です。

const [sort, setSort] = useState<SortSpec[]>([])

<VoxSheet columns={columns} totalRows={total} fetchRows={fetchRows}
    sort={sort} onSortChange={setSort} />

並べ替え方式（sortModes）

同じ列でも「テキストとして」か「数値として」かで並べ替え結果が変わる場合があります。Column.sortModes を指定するとヘッダに小さな ▾ ピッカーが出て、選んだ方式 id が SortSpec.mode に載ります。実際の比較はバックエンドが解釈します（グリッドは id を運ぶだけでトランスポート非依存）。sortModes 未指定の列は従来どおりで mode を送らないため、既定はバックエンドの素の（テキスト）並べ替えになります。

const columns: Column[] = [
    { name: "code", sortModes: [
        { id: "text", label: "テキスト" },
        { id: "numeric", label: "数値" },
    ], defaultSortMode: "text" },
]
// fetchRows には例えば { column: "code", direction: "asc", mode: "numeric" } が渡る
// → サーバ側で mode を ORDER BY に変換する。

フィルタ

フィルタ条件 UI はホストが所有します。グリッドは onFilterButtonClick(col, anchorRect) で「この列のフィルタを編集したい」と通知するので、ホストはその anchorRect 付近にポップオーバーを出し、確定後 filters を更新します。フィルタは AND 結合です。

type FilterOperator =
    | "=" | "!=" | ">" | ">=" | "<" | "<="
    | "contains" | "startsWith" | "endsWith"
    | "isNull" | "notNull"

type FilterSpec = { column: string; operator: FilterOperator; value?: CellValue }

ある列に2 件以上のフィルタが適用されているとき、ヘッダのフィルタボタンに件数バッジが表示され、複数条件を一目で把握できます。

検索

search にキーワードを渡すと fetchRows の Query.search に反映されます。ヒット箇所のハイライトとスクロールはホストが searchHighlights / currentSearchHit で制御します。

<VoxSheet ...
    search={keyword}
    searchHighlights={hits}
    currentSearchHit={hits[cursor] ?? null}
/>

編集とコミット

編集はまずローカル層に溜まります（ダーティ表示、onCellChange / onDirtyChange 通知）。ホストは任意のタイミングで getLocalEdits() を読み、各 row を fetchRows で受け取った ids で安定 ID に解決し、永続化後に clearLocalEdits() を呼びます。

const ref = useRef<VoxSheetHandle>(null)

async function save() {
    const edits = ref.current!.getLocalEdits()  // CellEdit[]
    // row → 安定 ID へ解決して PATCH 等で永続化
    await commitToServer(edits)
    ref.current!.clearLocalEdits()               // 成功後にクリア
}

<VoxSheet ref={ref} ... onDirtyChange={setDirty} />

type CellEdit = { row: number; col: number; oldValue: CellValue; newValue: CellValue }

選択と集計

選択は Excel 風の矩形レンジの配列です。onSelectionChange で選択範囲、onSelectionStats で件数・数値件数・合計・平均が得られます（数値が無い場合 sum / average は null）。

type CellAddress = { row: number; col: number }
type Selection = { start: CellAddress; end: CellAddress }
type SelectionStats = {
    count: number
    numericCount: number
    sum: number | null
    average: number | null
}

オートフィル

選択範囲右下のフィルハンドルをドラッグ／ダブルクリックすると onAutoFill が呼ばれます。実際の値生成ロジックはホストが担います。

onAutoFill={(p) => {
    // p.sourceRange: 元の選択, p.direction: "down"|"up"|"left"|"right"
    // p.toEnd: ダブルクリックで列末尾まで
}}

キーボード操作

IME は compositionend で確定されます。readOnly 時はコピー・全選択・ナビゲーションのみ有効です。

行の固定

frozenRows を指定すると、先頭 N 行を本体スクロールの外側に置いた固定バンドに描画します。バンドはその場に留まり、残りのグリッドだけが縦スクロールします。横スクロールのみバンドに同期するため、固定セルは対応する列と揃ったままになります。本体スクロール領域は [frozenRows, total) の行を担当するので、固定行が二重に表示されることはありません。

固定行は通常の行と同じように選択・編集でき、それらを含む先頭側のチャンクはスクロール位置に依らず常に取得されます。既定値 0 で固定は無効です。列を固定する場合は列の固定を参照してください。

<VoxSheet columns={columns} totalRows={total} fetchRows={fetchRows} frozenRows={2} />

列の固定

frozenColumns を指定すると、先頭 N 列を左に固定します。残りのグリッドを横スクロールしても常に見えたままになり（sticky で実装）、列幅や行高は本体とずれません。frozenRows と組み合わせると、左上の交差部分が縦横どちらのスクロールでも固定されます。

既定値 0 で固定は無効です。

<VoxSheet columns={columns} totalRows={total} fetchRows={fetchRows} frozenColumns={1} />

列の並べ替え

onColumnReorder を指定すると、列ヘッダをドラッグして並べ替えられます。ドラッグ中は挿入位置のインジケータが出て、ドロップで onColumnReorder(from, to) が発火します。列順はホストが所有します（columns 配列を並べ替えて反映）。

データは位置ベース（data[i][j] は columns 対応）のため、並べ替え後は fetchRows が各行のセルを現在の列順で返すようにしてください（バックエンドがその順で返す、またはクライアントで並べ替える）。

onColumnReorder={(from, to) => {
    setColumns((cols) => {
        const next = [...cols]
        const [moved] = next.splice(from, 1)
        next.splice(to, 0, moved)
        return next
    })
}}

命令的ハンドル（ref）

ref 経由で VoxSheetHandle を取得し、スクロール・選択・編集・Undo などを命令的に操作できます。

スタイリング・テーマ

スタイルは vox- クラスと --vox-* CSS 変数で自己完結しています。@lembryo/voxsheet/styles.css を読み込み、変数やクラスを上書きしてテーマ調整します。ダークモードは prefers-color-scheme に追従し、theme prop で強制もできます。

.vox-sheet {
    --vox-row-height: 32px;
    --vox-color-accent: #06c755;
}

• density で行高とフォントをまとめて切替（compact / normal / comfortable）。
• rowHeight は density より優先。
• theme は data-vox-theme 属性を設定（light / dark / system）。

国際化（labels）

内蔵 UI 文言は labels（Partial<VoxLabels>）で部分上書きできます。

<VoxSheet ...
    labels={{
        loading: "読み込み中…",
        empty: "データがありません",
        contextCopy: "コピー",
        contextPaste: "貼り付け",
    }}
/>

キー一覧は 型リファレンス の VoxLabels を参照してください。

アイコン

ソート／フィルタのアイコンを差し替えられます。指定しないキーは内蔵アイコンが使われます。

<VoxSheet ...
    icons={{
        filter: ({ size }) => <MyFilterIcon width={size} />,
    }}
/>

差し替え可能なキー: sortAscending / sortDescending / sortUnsorted / filter / filterActive。

プラットフォームアダプタ

クリップボード・トースト通知・確認ダイアログ・ファイル保存の実装を注入できます。未指定時はブラウザ標準の挙動にフォールバックします。

<VoxSheet ...
    platform={{
        notify: (kind, message) => { showToast(kind, message); return id },
        confirm: async ({ message }) => window.confirm(message),
        clipboard: {
            readText: () => navigator.clipboard.readText(),
            writeText: (t) => navigator.clipboard.writeText(t),
        },
    }}
/>

型リファレンス

公開されている主要な型の一覧です。

type CellValue = string | number | boolean | null
type ColumnType = "string" | "number" | "date" | "boolean"
type ColumnAlign = "left" | "right" | "center"

type SortDirection = "asc" | "desc"
type SortMode = { id: string; label: string }
type SortSpec = { column: string; direction: SortDirection; mode?: string }

type FilterOperator =
    | "=" | "!=" | ">" | ">=" | "<" | "<="
    | "contains" | "startsWith" | "endsWith"
    | "isNull" | "notNull"
type FilterSpec = { column: string; operator: FilterOperator; value?: CellValue }

type CellAddress = { row: number; col: number }
type Selection = { start: CellAddress; end: CellAddress }
type SelectionStats = {
    count: number; numericCount: number
    sum: number | null; average: number | null
}

type CellEdit = { row: number; col: number; oldValue: CellValue; newValue: CellValue }
type CellContext = { row: number; col: number; value: CellValue; column: Column }

// 内蔵 UI 文言
type VoxLabels = {
    loading: string; empty: string
    contextCut: string; contextCopy: string; contextPaste: string
    contextInsertRowAbove: string; contextInsertRowBelow: string
    contextDeleteRows: string; contextUndo: string; contextRedo: string
    sortOptions: string; sortClear: string
    confirmLargeCopyTitle: string; confirmLargeCopyMessage: string
    confirmOk: string; confirmCancel: string
}

// アイコン
type IconName =
    "sortAscending" | "sortDescending" | "sortUnsorted" | "filter" | "filterActive"
type IconProps = { size?: number; className?: string }
type Icons = Partial<Record<IconName, (props: IconProps) => ReactElement>>

// プラットフォーム
type ToastKind = "loading" | "success" | "error" | "info"
type PlatformAdapter = {
    clipboard?: {
        readText?: () => Promise<string>
        writeText?: (text: string) => Promise<void>
    }
    notify?: (kind: ToastKind, message: string,
        opts?: { id?: string; durationMs?: number }) => string
    confirm?: (opts: { title?: string; message: string;
        confirmLabel?: string; cancelLabel?: string }) => Promise<boolean>
    saveFile?: (opts: { suggestedName: string; mimeType?: string;
        data: string | Blob }) => Promise<void>
}

制限事項

コールバック未指定のヘッダボタンは非表示になります（仕様）。