APG Patterns
English
English

Data Grid

ソート、行選択、範囲選択、セル編集機能を備えた高度なインタラクティブデータグリッド。

デモ

Name
Email
Role
Status
Alice Johnson
alice@example.com
Admin
Active
Bob Smith
bob@example.com
Editor
Active
Charlie Brown
charlie@example.com
Viewer
Inactive
Diana Prince
diana@example.com
Admin
Active
Eve Wilson
eve@example.com
Editor
Active

Navigation: Arrow keys to navigate, Home/End for row bounds, Ctrl+Home/End for grid bounds.

Sorting: Click or press Enter/Space on a sortable column header to cycle sort direction.

Row Selection: Click checkboxes or press Space to select/deselect rows.

Editing: Press Enter or F2 on an editable cell (Role/Status, indicated by pen icon) to edit. Role uses combobox with autocomplete, Status uses select dropdown. Escape to cancel.

デモのみ表示 →

キーボード操作
ナビゲーション
セル間を移動
Home / End
行の最初 / 最後のセルへ
Ctrl + Home
グリッド先頭のセルへ
Ctrl + End
グリッド末尾のセルへ
Page Up / Page Down
ページ単位でジャンプ
ソート
Enter / Space
列をソート(ヘッダー上で)
選択
Space
行選択をトグル(チェックボックス上で)
Shift + 矢印
セル選択を拡張
Ctrl + A
全セルを選択
編集
Enter / F2
セル編集を開始
Escape
編集をキャンセル
Tab
セル内ウィジェット間を移動

Data Grid vs Grid

Data Grid は基本的な Grid パターンを拡張し、データ操作のための追加機能を提供します。

機能 Grid Data Grid
2Dナビゲーション あり あり
セル選択 あり あり
列ソート なし あり(aria-sort)
行選択 なし あり(チェックボックス)
範囲選択 なし あり(Shift+矢印)
セル編集 なし あり(Enter/F2)
ヘッダーナビゲーション なし あり(ソート可能ヘッダー)

アクセシビリティ

データグリッドを使用するタイミング

データグリッドは、基本的なgridロールをスプレッドシートのような機能で拡張します。次の機能が必要な場合に使用します:

  • ソート: クリック/キーボードでデータをソートする列ヘッダー
  • 行選択: チェックボックスベースの行全体の選択
  • 範囲選択: Shift+矢印で複数のセルを選択
  • セル編集: Enter/F2で編集を開始、Escapeでキャンセルするインプレース編集

単純な静的テーブルには、ネイティブの

要素を使用してください。これらの機能を持たないインタラクティブなグリッドには、基本的なgridパターンを使用してください。

WAI-ARIA ロール

ロール 対象要素 説明
grid コンテナ グリッドとして要素を識別します。グリッドはセルの行を含みます。
row 各行 セルの行を識別します
gridcell 各セル グリッド内のインタラクティブなセルを識別します
rowheader 行ヘッダーセル 行のヘッダーとしてセルを識別します
columnheader 列ヘッダーセル 列のヘッダーとしてセルを識別します

APG データグリッドの例 (opens in new tab)

WAI-ARIA プロパティ(グリッドコンテナ)

属性 必須 説明
role="grid" - はい コンテナをグリッドとして識別
aria-label String はい* グリッドのアクセシブルな名前
aria-labelledby ID reference はい* aria-labelの代替
aria-multiselectable true いいえ マルチセレクト(行またはセル)が有効な場合に存在
aria-readonly true いいえ グリッド全体が読み取り専用の場合に存在
aria-rowcount Number (1-based) いいえ 仮想化のための総行数
aria-colcount Number (1-based) いいえ 仮想化のための総列数

* aria-labelまたはaria-labelledbyのいずれかが必須です。

WAI-ARIA ステート(列ヘッダー)

属性 必須 説明
aria-sort ascending | descending | none | other はい* 現在のソート方向(ソート可能なヘッダーのみ)
tabindex 0 | -1 はい* ローヴィングタブインデックス(ソート可能なヘッダーのみ)

* ソート可能な列ヘッダーにのみ必須です。

WAI-ARIA ステート(行)

属性 必須 説明
aria-selected true | false はい* 行選択状態(rowSelectableの場合)
aria-disabled true いいえ 行が無効であることを示す
aria-rowindex Number (1-based) いいえ 仮想化のための行位置

* 行選択が有効な場合にのみ必須です。

WAI-ARIA ステート(グリッドセル)

属性 必須 説明
tabindex 0 | -1 はい フォーカス管理のためのローヴィングタブインデックス
aria-selected true | false いいえ* セル選択状態(セル選択可能な場合)
aria-readonly true | false いいえ* セルの編集可能性(グリッドが編集可能な場合)
aria-disabled true いいえ セルが無効であることを示す
aria-colindex Number (1-based) いいえ 仮想化のための列位置

* 選択/編集がサポートされている場合、すべてのgridcellに対応する属性が必要です。

キーボードサポート

2Dナビゲーション

キー アクション
フォーカスを右に1セル移動
フォーカスを左に1セル移動
フォーカスを1行下に移動(ヘッダーから最初のデータ行へ)
フォーカスを1行上に移動(最初の行からソート可能な場合ヘッダーへ)
Home フォーカスを行の最初のセルに移動
End フォーカスを行の最後のセルに移動
Ctrl + Home フォーカスをグリッドの最初のセルに移動
Ctrl + End フォーカスをグリッドの最後のセルに移動
PageDown フォーカスをページサイズ分下に移動
PageUp フォーカスをページサイズ分上に移動

ソート(列ヘッダー)

キー アクション
Enter ソート方向を循環(なし → 昇順 → 降順 → 昇順)
Space ソート方向を循環

範囲選択

キー アクション
Shift + 選択を下に拡張
Shift + 選択を上に拡張
Shift + 選択を右に拡張
Shift + 選択を左に拡張
Shift + Home 選択を行の先頭まで拡張
Shift + End 選択を行の末尾まで拡張
Ctrl + Shift + Home 選択をグリッドの先頭まで拡張
Ctrl + Shift + End 選択をグリッドの末尾まで拡張

セル編集

キー アクション
Enter 編集モードに入る(編集可能なセル)または編集をコミット(編集モード中)
F2 編集モードに入る
Escape 編集をキャンセルして元の値を復元
Tab 編集をコミット(編集モード中)

選択とアクティベーション

キー アクション
Space フォーカスされたセルを選択/解除または行チェックボックスを切り替え
Ctrl + A すべてのセルを選択(マルチセレクト可能な場合)

フォーカス管理

このコンポーネントはローヴィングタブインデックスをフォーカス管理に使用します:

  • tabindex="0"を持つ要素は1つだけ(現在のフォーカス位置)
  • 他のすべてのフォーカス可能な要素はtabindex="-1"
  • グリッドは単一のタブストップ(Tabでグリッドに入り、Shift+Tabで出る)
  • ソート可能な列ヘッダーはローヴィングタブインデックスに参加(ソート不可のヘッダーはフォーカス不可)
  • 最初のデータ行からの上矢印は同じ列のソート可能なヘッダーに移動
  • ヘッダーからの下矢印は同じ列の最初のデータ行に移動
  • 編集モード:フォーカスは入力フィールドに移動、編集が終了するまでグリッドナビゲーションは無効
  • フォーカスメモリ:グリッドを離れて再び入るときに最後にフォーカスされた要素を記憶

行選択の動作

  • 行選択チェックボックスは専用の列(gridcell)に配置
  • 各行のチェックボックスにはアクセシブルなラベルがある(例:"Select row user1")
  • rowMultiselectableがtrueの場合、ヘッダーに「全て選択」チェックボックスが表示
  • 一部(すべてではない)の行が選択されている場合、「全て選択」チェックボックスは不確定状態を表示
  • 行の選択状態は行要素のaria-selectedで反映

編集モードの動作

  • editable: trueのセルのみが編集モードに入れる
  • readonly: trueのセルは編集可能でも編集できない
  • グリッドレベルのreadonlyプロップはすべての編集を無効化
  • セルのaria-readonlyはスクリーンリーダーに編集可能性を示す
  • 編集中、フォーカスはセル内の入力フィールドにある
  • 編集モード中はグリッドキーボードナビゲーション(矢印、Home、End)は抑制
  • 編集終了時(Enter、Tab、blur)、フォーカスはセルに戻る
  • キャンセル時(Escape)、元の値が復元される

ソースコード

DataGrid.tsx
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';

// =============================================================================
// Types
// =============================================================================

export type SortDirection = 'ascending' | 'descending' | 'none' | 'other';

// =============================================================================
// Helper Functions
// =============================================================================

/** Get sort indicator character based on sort direction */
function getSortIndicator(direction?: SortDirection): string {
  if (direction === 'ascending') return ' ▲';
  if (direction === 'descending') return ' ▼';
  return ' ⇅';
}
export type EditType = 'text' | 'select' | 'combobox';

export interface DataGridCellData {
  id: string;
  value: string | number;
  disabled?: boolean;
  colspan?: number;
  rowspan?: number;
  editable?: boolean;
  readonly?: boolean;
}

export interface DataGridColumnDef {
  id: string;
  header: string;
  sortable?: boolean;
  sortDirection?: SortDirection;
  colspan?: number;
  isRowLabel?: boolean; // This column provides accessible labels for row checkboxes
  editable?: boolean; // Column-level editable flag
  editType?: EditType; // Type of editor: text, select, or combobox
  options?: string[]; // Options for select/combobox
}

export interface DataGridRowData {
  id: string;
  cells: DataGridCellData[];
  hasRowHeader?: boolean;
  disabled?: boolean;
}

export interface DataGridProps {
  columns: DataGridColumnDef[];
  rows: DataGridRowData[];

  // Accessible name (one required)
  ariaLabel?: string;
  ariaLabelledby?: string;

  // Row Selection
  rowSelectable?: boolean;
  rowMultiselectable?: boolean;
  selectedRowIds?: string[];
  defaultSelectedRowIds?: string[];
  onRowSelectionChange?: (rowIds: string[]) => void;

  // Sorting
  onSort?: (columnId: string, direction: SortDirection) => void;

  // Range Selection
  enableRangeSelection?: boolean;
  onRangeSelect?: (cellIds: string[]) => void;

  // Cell Editing
  editable?: boolean;
  readonly?: boolean;
  editingCellId?: string | null;
  onEditStart?: (cellId: string, rowId: string, colId: string) => void;
  onEditEnd?: (cellId: string, value: string, cancelled: boolean) => void;
  onCellValueChange?: (cellId: string, newValue: string) => void;

  // Focus
  focusedId?: string | null;
  defaultFocusedId?: string;
  onFocusChange?: (focusedId: string | null) => void;

  // Cell Selection (from Grid)
  selectable?: boolean;
  multiselectable?: boolean;
  selectedIds?: string[];
  defaultSelectedIds?: string[];
  onSelectionChange?: (selectedIds: string[]) => void;

  // Virtualization
  totalColumns?: number;
  totalRows?: number;
  startRowIndex?: number; // 1-based
  startColIndex?: number; // 1-based

  // Behavior
  wrapNavigation?: boolean;
  enablePageNavigation?: boolean;
  pageSize?: number;

  // Callbacks
  onCellActivate?: (cellId: string, rowId: string, colId: string) => void;
  renderCell?: (cell: DataGridCellData, rowId: string, colId: string) => React.ReactNode;

  // Styling
  className?: string;
}

// =============================================================================
// Helper Functions
// =============================================================================

function getNextSortDirection(current: SortDirection | undefined): SortDirection {
  switch (current) {
    case 'ascending':
      return 'descending';
    case 'descending':
      return 'ascending';
    case 'none':
    default:
      return 'ascending';
  }
}

// =============================================================================
// Component
// =============================================================================

export function DataGrid({
  columns,
  rows,
  ariaLabel,
  ariaLabelledby,
  rowSelectable = false,
  rowMultiselectable = false,
  selectedRowIds: controlledSelectedRowIds,
  defaultSelectedRowIds = [],
  onRowSelectionChange,
  onSort,
  enableRangeSelection = false,
  onRangeSelect,
  editable = false,
  readonly = false,
  editingCellId: controlledEditingCellId,
  onEditStart,
  onEditEnd,
  onCellValueChange,
  focusedId: controlledFocusedId,
  defaultFocusedId,
  onFocusChange,
  selectable = false,
  multiselectable = false,
  selectedIds: controlledSelectedIds,
  defaultSelectedIds = [],
  onSelectionChange,
  totalColumns,
  totalRows,
  startRowIndex = 1,
  startColIndex = 1,
  wrapNavigation = false,
  enablePageNavigation = false,
  pageSize = 5,
  onCellActivate,
  renderCell,
  className,
}: DataGridProps) {
  // ==========================================================================
  // State
  // ==========================================================================

  // Row selection
  const [internalSelectedRowIds, setInternalSelectedRowIds] =
    useState<string[]>(defaultSelectedRowIds);
  const selectedRowIds = controlledSelectedRowIds ?? internalSelectedRowIds;

  // Cell selection
  const [internalSelectedIds, setInternalSelectedIds] = useState<string[]>(defaultSelectedIds);
  const selectedIds = controlledSelectedIds ?? internalSelectedIds;

  // Focus
  const [internalFocusedId, setInternalFocusedId] = useState<string | null>(() => {
    if (defaultFocusedId) return defaultFocusedId;
    // Default to first focusable item based on row selection mode
    // rowMultiselectable: header checkbox cell is first (Select all rows)
    // rowSelectable only: first row's checkbox cell
    // Otherwise: first data cell
    if (rowSelectable && rowMultiselectable) {
      return 'header-checkbox';
    }
    if (rowSelectable) {
      return rows[0] ? `checkbox-${rows[0].id}` : null;
    }
    return rows[0]?.cells[0]?.id ?? null;
  });
  const focusedId = controlledFocusedId !== undefined ? controlledFocusedId : internalFocusedId;

  // Edit mode
  const [internalEditingCellId, setInternalEditingCellId] = useState<string | null>(null);
  const editingCellId =
    controlledEditingCellId !== undefined ? controlledEditingCellId : internalEditingCellId;
  const [editValue, setEditValue] = useState<string>('');
  const [originalEditValue, setOriginalEditValue] = useState<string>('');
  const [editingColId, setEditingColId] = useState<string | null>(null);

  // Combobox state
  const [comboboxExpanded, setComboboxExpanded] = useState(false);
  const [comboboxActiveIndex, setComboboxActiveIndex] = useState(-1);
  const [filteredOptions, setFilteredOptions] = useState<string[]>([]);

  // Range selection anchor
  const [anchorCellId, setAnchorCellId] = useState<string | null>(null);

  // Ref to track if edit is being ended (to prevent double callback)
  const isEndingEditRef = useRef(false);

  const gridRef = useRef<HTMLDivElement>(null);
  const cellRefs = useRef<Map<string, HTMLDivElement>>(new Map());
  const headerRefs = useRef<Map<string, HTMLDivElement>>(new Map());
  const inputRef = useRef<HTMLInputElement>(null);
  const selectRef = useRef<HTMLSelectElement>(null);
  const listboxRef = useRef<HTMLUListElement>(null);

  // ==========================================================================
  // Computed values
  // ==========================================================================

  // Check if we have sortable headers
  const hasSortableHeaders = useMemo(() => columns.some((col) => col.sortable), [columns]);

  // Check if header row has focusable items (sortable headers OR header checkbox)
  const hasHeaderFocusable = useMemo(
    () => hasSortableHeaders || (rowSelectable && rowMultiselectable),
    [hasSortableHeaders, rowSelectable, rowMultiselectable]
  );

  // Find the column that provides row labels (for aria-labelledby on row checkboxes)
  // Priority: 1. Column with isRowLabel: true, 2. First column (fallback)
  const rowLabelColumn = useMemo(() => {
    const labelColumn = columns.find((col) => col.isRowLabel);
    return labelColumn ?? columns[0];
  }, [columns]);

  // Build a flat list of focusable items (sortable headers + cells)
  const focusableItems = useMemo(() => {
    const items: Array<{
      id: string;
      type: 'header' | 'cell' | 'checkbox' | 'header-checkbox';
      rowIndex: number; // -1 for header
      colIndex: number;
      columnId?: string;
      rowId?: string;
      cell?: DataGridCellData;
      disabled?: boolean;
    }> = [];

    // Column offset when rowSelectable is enabled (checkbox column takes index 0)
    const colOffset = rowSelectable ? 1 : 0;

    // Header checkbox cell at row index -1, colIndex 0 (when rowMultiselectable)
    if (rowSelectable && rowMultiselectable) {
      items.push({
        id: 'header-checkbox',
        type: 'header-checkbox',
        rowIndex: -1,
        colIndex: 0,
      });
    }

    // Sortable headers at row index -1
    columns.forEach((col, colIndex) => {
      if (col.sortable) {
        items.push({
          id: `header-${col.id}`,
          type: 'header',
          rowIndex: -1,
          colIndex: colIndex + colOffset,
          columnId: col.id,
        });
      }
    });

    // Checkbox cells and data cells
    rows.forEach((row, rowIndex) => {
      // Add checkbox cell if row selection is enabled
      if (rowSelectable) {
        items.push({
          id: `checkbox-${row.id}`,
          type: 'checkbox',
          rowIndex,
          colIndex: 0,
          rowId: row.id,
          disabled: row.disabled,
        });
      }

      // Data cells
      row.cells.forEach((cell, colIndex) => {
        items.push({
          id: cell.id,
          type: 'cell',
          rowIndex,
          colIndex: colIndex + colOffset,
          rowId: row.id,
          columnId: columns[colIndex]?.id,
          cell,
          disabled: cell.disabled || row.disabled,
        });
      });
    });

    return items;
  }, [columns, rows, rowSelectable, rowMultiselectable]);

  // Map for quick lookup
  const itemById = useMemo(() => {
    const map = new Map<string, (typeof focusableItems)[0]>();
    focusableItems.forEach((item) => map.set(item.id, item));
    return map;
  }, [focusableItems]);

  // Get position of a cell/header
  const getItemPosition = useCallback(
    (id: string) => {
      const item = itemById.get(id);
      if (!item) return null;
      return { rowIndex: item.rowIndex, colIndex: item.colIndex };
    },
    [itemById]
  );

  // Get item at position
  const getItemAt = useCallback(
    (rowIndex: number, colIndex: number) => {
      if (rowIndex === -1) {
        // Header row - find header-checkbox or sortable header at this column
        return focusableItems.find(
          (item) =>
            (item.type === 'header' || item.type === 'header-checkbox') &&
            item.rowIndex === -1 &&
            item.colIndex === colIndex
        );
      }
      // Data row - find cell or checkbox at this position
      return focusableItems.find(
        (item) =>
          (item.type === 'cell' || item.type === 'checkbox') &&
          item.rowIndex === rowIndex &&
          item.colIndex === colIndex
      );
    },
    [focusableItems]
  );

  const getColumnCount = useCallback(
    () => columns.length + (rowSelectable ? 1 : 0),
    [columns, rowSelectable]
  );
  const getRowCount = useCallback(() => rows.length, [rows]);

  // ==========================================================================
  // Focus Management
  // ==========================================================================

  const setFocusedId = useCallback(
    (id: string | null) => {
      setInternalFocusedId(id);
      onFocusChange?.(id);
    },
    [onFocusChange]
  );

  const focusItem = useCallback(
    (id: string) => {
      const item = itemById.get(id);
      if (!item) return;

      if (item.type === 'header') {
        const headerEl = headerRefs.current.get(item.columnId!);
        if (headerEl) {
          headerEl.focus();
          setFocusedId(id);
        }
      } else if (item.type === 'header-checkbox') {
        const cellEl = cellRefs.current.get(id);
        if (cellEl) {
          cellEl.focus();
          setFocusedId(id);
        }
      } else {
        const cellEl = cellRefs.current.get(id);
        if (cellEl) {
          cellEl.focus();
          setFocusedId(id);
        }
      }
    },
    [itemById, setFocusedId]
  );

  // Find next focusable item (skipping disabled cells)
  const findNextFocusable = useCallback(
    (
      startRowIndex: number,
      startColIndex: number,
      direction: 'right' | 'left' | 'up' | 'down',
      skipDisabled = true
    ): (typeof focusableItems)[0] | null => {
      const colCount = getColumnCount();
      const rowCount = getRowCount();

      let rowIdx = startRowIndex;
      let colIdx = startColIndex;

      const step = () => {
        switch (direction) {
          case 'right':
            colIdx++;
            if (colIdx >= colCount) {
              if (wrapNavigation) {
                colIdx = 0;
                rowIdx++;
                if (rowIdx >= rowCount) return false;
              } else {
                return false;
              }
            }
            break;
          case 'left':
            colIdx--;
            if (colIdx < 0) {
              if (wrapNavigation) {
                colIdx = colCount - 1;
                rowIdx--;
                // Allow going up to header row (-1) if header has focusable items
                if (rowIdx < (hasHeaderFocusable ? -1 : 0)) return false;
              } else {
                return false;
              }
            }
            break;
          case 'down':
            rowIdx++;
            if (rowIdx >= rowCount) return false;
            break;
          case 'up':
            rowIdx--;
            // Allow going up to header row (-1) if header has focusable items
            if (rowIdx < (hasHeaderFocusable ? -1 : 0)) return false;
            break;
        }
        return true;
      };

      // Take one step first
      if (!step()) return null;

      // Find non-disabled item
      let iterations = 0;
      const maxIterations = colCount * (rowCount + 1);

      while (iterations < maxIterations) {
        const item = getItemAt(rowIdx, colIdx);
        if (item) {
          // For header row (-1), always allow (headers are not disabled)
          if (rowIdx === -1) {
            return item;
          }
          // For data cells, check disabled state
          if (!skipDisabled || !item.disabled) {
            return item;
          }
        }
        if (!step()) break;
        iterations++;
      }

      return null;
    },
    [getColumnCount, getRowCount, wrapNavigation, hasHeaderFocusable, getItemAt]
  );

  // ==========================================================================
  // Row Selection
  // ==========================================================================

  const setSelectedRowIds = useCallback(
    (ids: string[]) => {
      setInternalSelectedRowIds(ids);
      onRowSelectionChange?.(ids);
    },
    [onRowSelectionChange]
  );

  const toggleRowSelection = useCallback(
    (rowId: string, row: DataGridRowData) => {
      if (!rowSelectable || row.disabled) return;

      if (rowMultiselectable) {
        const newIds = selectedRowIds.includes(rowId)
          ? selectedRowIds.filter((id) => id !== rowId)
          : [...selectedRowIds, rowId];
        setSelectedRowIds(newIds);
      } else {
        const newIds = selectedRowIds.includes(rowId) ? [] : [rowId];
        setSelectedRowIds(newIds);
      }
    },
    [rowSelectable, rowMultiselectable, selectedRowIds, setSelectedRowIds]
  );

  // Toggle all row selection
  const toggleAllRowSelection = useCallback(() => {
    if (!rowSelectable || !rowMultiselectable) return;

    const allRowIds = rows.filter((r) => !r.disabled).map((r) => r.id);
    const allSelected = allRowIds.every((id) => selectedRowIds.includes(id));

    if (allSelected) {
      setSelectedRowIds([]);
    } else {
      setSelectedRowIds(allRowIds);
    }
  }, [rowSelectable, rowMultiselectable, rows, selectedRowIds, setSelectedRowIds]);

  // Get select all checkbox state
  const getSelectAllState = useCallback((): 'all' | 'some' | 'none' => {
    const allRowIds = rows.filter((r) => !r.disabled).map((r) => r.id);
    if (allRowIds.length === 0) return 'none';

    const selectedCount = allRowIds.filter((id) => selectedRowIds.includes(id)).length;
    if (selectedCount === 0) return 'none';
    if (selectedCount === allRowIds.length) return 'all';
    return 'some';
  }, [rows, selectedRowIds]);

  // ==========================================================================
  // Cell Selection
  // ==========================================================================

  const setSelectedIds = useCallback(
    (ids: string[]) => {
      setInternalSelectedIds(ids);
      onSelectionChange?.(ids);
    },
    [onSelectionChange]
  );

  const toggleSelection = useCallback(
    (cellId: string, cell: DataGridCellData) => {
      if (!selectable || cell.disabled) return;

      if (multiselectable) {
        const newIds = selectedIds.includes(cellId)
          ? selectedIds.filter((id) => id !== cellId)
          : [...selectedIds, cellId];
        setSelectedIds(newIds);
      } else {
        const newIds = selectedIds.includes(cellId) ? [] : [cellId];
        setSelectedIds(newIds);
      }
    },
    [selectable, multiselectable, selectedIds, setSelectedIds]
  );

  const selectAll = useCallback(() => {
    if (!selectable || !multiselectable) return;

    const allIds = focusableItems
      .filter((item) => item.type === 'cell' && !item.disabled)
      .map((item) => item.id);
    setSelectedIds(allIds);
  }, [selectable, multiselectable, focusableItems, setSelectedIds]);

  // ==========================================================================
  // Range Selection
  // ==========================================================================

  const getCellsInRange = useCallback(
    (startId: string, endId: string): string[] => {
      const startItem = itemById.get(startId);
      const endItem = itemById.get(endId);
      if (!startItem || !endItem || startItem.type === 'header' || endItem.type === 'header') {
        return [];
      }

      const minRow = Math.min(startItem.rowIndex, endItem.rowIndex);
      const maxRow = Math.max(startItem.rowIndex, endItem.rowIndex);
      const minCol = Math.min(startItem.colIndex, endItem.colIndex);
      const maxCol = Math.max(startItem.colIndex, endItem.colIndex);

      const cellIds: string[] = [];
      for (let r = minRow; r <= maxRow; r++) {
        for (let c = minCol; c <= maxCol; c++) {
          const item = getItemAt(r, c);
          if (item && item.type === 'cell' && !item.disabled) {
            cellIds.push(item.id);
          }
        }
      }
      return cellIds;
    },
    [itemById, getItemAt]
  );

  const extendRangeSelection = useCallback(
    (currentCellId: string, newFocusId: string) => {
      if (!enableRangeSelection) return;

      // If no anchor yet, use the current cell (before movement) as anchor
      const anchor = anchorCellId ?? currentCellId;
      if (!anchorCellId) {
        setAnchorCellId(currentCellId);
      }

      const cellIds = getCellsInRange(anchor, newFocusId);
      onRangeSelect?.(cellIds);
    },
    [enableRangeSelection, anchorCellId, getCellsInRange, onRangeSelect]
  );

  // ==========================================================================
  // Sorting
  // ==========================================================================

  const handleSort = useCallback(
    (columnId: string) => {
      const column = columns.find((col) => col.id === columnId);
      if (!column?.sortable || !onSort) return;

      const nextDirection = getNextSortDirection(column.sortDirection);
      onSort(columnId, nextDirection);
    },
    [columns, onSort]
  );

  // ==========================================================================
  // Cell Editing
  // ==========================================================================

  // Helper to check if a cell is editable (cell-level or column-level)
  const isCellEditable = useCallback(
    (cell: DataGridCellData, colId: string) => {
      if (cell.readonly) return false;
      // Cell-level editable takes priority
      if (cell.editable !== undefined) return cell.editable;
      // Column-level editable
      const column = columns.find((col) => col.id === colId);
      return column?.editable ?? false;
    },
    [columns]
  );

  // Helper to get column's editType
  const getColumnEditType = useCallback(
    (colId: string): EditType => {
      const column = columns.find((col) => col.id === colId);
      return column?.editType ?? 'text';
    },
    [columns]
  );

  // Helper to get column's options
  const getColumnOptions = useCallback(
    (colId: string): string[] => {
      const column = columns.find((col) => col.id === colId);
      return column?.options ?? [];
    },
    [columns]
  );

  const startEdit = useCallback(
    (cellId: string, rowId: string, colId: string) => {
      if (!editable || readonly) return;

      const item = itemById.get(cellId);
      if (!item || item.type === 'header' || !item.cell) return;

      // Check if cell is editable (cell-level or column-level)
      if (!isCellEditable(item.cell, colId)) return;

      const value = String(item.cell.value);
      setOriginalEditValue(value);
      setEditValue(value);
      setEditingColId(colId);
      setInternalEditingCellId(cellId);

      // Initialize combobox state if editType is combobox
      const editType = getColumnEditType(colId);
      if (editType === 'combobox') {
        const options = getColumnOptions(colId);
        setFilteredOptions(options);
        setComboboxExpanded(true);
        setComboboxActiveIndex(-1);
      }

      onEditStart?.(cellId, rowId, colId);
    },
    [editable, readonly, itemById, isCellEditable, getColumnEditType, getColumnOptions, onEditStart]
  );

  const endEdit = useCallback(
    (cellId: string, cancelled: boolean, explicitValue?: string) => {
      // Guard: prevent double callback using ref
      if (isEndingEditRef.current) return;
      // Guard: only end edit if we're currently editing this cell
      if (internalEditingCellId !== cellId) return;

      isEndingEditRef.current = true;
      // Use explicit value if provided (for combobox/select option clicks),
      // otherwise fall back to current editValue state
      const finalValue = cancelled ? originalEditValue : (explicitValue ?? editValue);
      setInternalEditingCellId(null);
      setEditingColId(null);
      setComboboxExpanded(false);
      setComboboxActiveIndex(-1);
      onEditEnd?.(cellId, finalValue, cancelled);

      // Focus back to cell
      const cellEl = cellRefs.current.get(cellId);
      if (cellEl) {
        cellEl.focus();
      }

      // Reset the flag after the current event loop
      setTimeout(() => {
        isEndingEditRef.current = false;
      }, 0);
    },
    [editValue, originalEditValue, onEditEnd, internalEditingCellId]
  );

  // ==========================================================================
  // Keyboard Handling - Header
  // ==========================================================================

  const handleHeaderKeyDown = useCallback(
    (event: React.KeyboardEvent, column: DataGridColumnDef) => {
      const pos = getItemPosition(`header-${column.id}`);
      if (!pos) return;

      const { colIndex } = pos;
      const { key, ctrlKey } = event;

      let handled = true;

      switch (key) {
        case 'ArrowRight': {
          // colIndex includes colOffset, so we need to adjust for columns array access
          const colOffset = rowSelectable ? 1 : 0;
          // Find next sortable header or wrap to data if none
          let nextColIdx = colIndex - colOffset + 1;
          while (nextColIdx < columns.length) {
            if (columns[nextColIdx].sortable) {
              focusItem(`header-${columns[nextColIdx].id}`);
              return (event.preventDefault(), event.stopPropagation());
            }
            nextColIdx++;
          }
          // No more sortable headers to the right, stay at current
          handled = false;
          break;
        }
        case 'ArrowLeft': {
          // colIndex includes colOffset, so we need to adjust for columns array access
          const colOffset = rowSelectable ? 1 : 0;
          let prevColIdx = colIndex - colOffset - 1;
          while (prevColIdx >= 0) {
            if (columns[prevColIdx].sortable) {
              focusItem(`header-${columns[prevColIdx].id}`);
              return (event.preventDefault(), event.stopPropagation());
            }
            prevColIdx--;
          }
          // No more sortable headers to the left, try header checkbox
          if (rowMultiselectable) {
            focusItem('header-checkbox');
            break;
          }
          handled = false;
          break;
        }
        case 'ArrowDown': {
          // Move to first data row, same column
          // colIndex includes colOffset, but rows[].cells[] doesn't include checkbox column
          const colOffset = rowSelectable ? 1 : 0;
          const cellColIndex = colIndex - colOffset;
          const firstRowCell = rows[0]?.cells[cellColIndex];
          if (firstRowCell) {
            focusItem(firstRowCell.id);
          }
          break;
        }
        case 'Home': {
          if (ctrlKey) {
            // Ctrl+Home: Go to first sortable header or first cell
            const firstSortable = columns.find((col) => col.sortable);
            if (firstSortable) {
              focusItem(`header-${firstSortable.id}`);
            } else {
              const firstCell = rows[0]?.cells[0];
              if (firstCell) focusItem(firstCell.id);
            }
          } else {
            // Home: First sortable header in row
            const firstSortable = columns.find((col) => col.sortable);
            if (firstSortable) {
              focusItem(`header-${firstSortable.id}`);
            }
          }
          break;
        }
        case 'End': {
          if (ctrlKey) {
            // Ctrl+End: Go to last cell in grid
            const lastRow = rows[rows.length - 1];
            const lastCell = lastRow?.cells[lastRow.cells.length - 1];
            if (lastCell) focusItem(lastCell.id);
          } else {
            // End: Last sortable header in row
            const lastSortable = [...columns].reverse().find((col) => col.sortable);
            if (lastSortable) {
              focusItem(`header-${lastSortable.id}`);
            }
          }
          break;
        }
        case 'Enter':
        case ' ': {
          if (column.sortable) {
            handleSort(column.id);
          }
          break;
        }
        default:
          handled = false;
      }

      if (handled) {
        event.preventDefault();
        event.stopPropagation();
      }
    },
    [columns, rows, getItemPosition, focusItem, handleSort, rowMultiselectable]
  );

  // ==========================================================================
  // Keyboard Handling - Header Checkbox Cell
  // ==========================================================================

  const handleHeaderCheckboxKeyDown = useCallback(
    (event: React.KeyboardEvent) => {
      const { key, ctrlKey } = event;
      let handled = true;

      switch (key) {
        case 'ArrowRight': {
          // Move to first sortable header if exists
          const firstSortable = columns.find((col) => col.sortable);
          if (firstSortable) {
            focusItem(`header-${firstSortable.id}`);
          }
          break;
        }
        case 'ArrowLeft': {
          // Already at leftmost position
          handled = false;
          break;
        }
        case 'ArrowDown': {
          // Move to first data row checkbox
          if (rows[0]) {
            focusItem(`checkbox-${rows[0].id}`);
          }
          break;
        }
        case 'ArrowUp': {
          // Already at top row
          handled = false;
          break;
        }
        case 'Home': {
          // Already at home position for header row
          if (ctrlKey) {
            // Stay at current position (first cell in grid)
          }
          break;
        }
        case 'End': {
          if (ctrlKey) {
            // Go to last cell in grid
            const lastRow = rows[rows.length - 1];
            const lastCell = lastRow?.cells[lastRow.cells.length - 1];
            if (lastCell) focusItem(lastCell.id);
          } else {
            // Go to last sortable header or stay
            const lastSortable = [...columns].reverse().find((col) => col.sortable);
            if (lastSortable) {
              focusItem(`header-${lastSortable.id}`);
            }
          }
          break;
        }
        case ' ':
        case 'Enter': {
          toggleAllRowSelection();
          break;
        }
        default:
          handled = false;
      }

      if (handled) {
        event.preventDefault();
        event.stopPropagation();
      }
    },
    [columns, rows, focusItem, toggleAllRowSelection]
  );

  // ==========================================================================
  // Keyboard Handling - Cell
  // ==========================================================================

  const handleCellKeyDown = useCallback(
    (event: React.KeyboardEvent, cell: DataGridCellData, rowId: string, colId: string) => {
      // If in edit mode, handle differently
      if (editingCellId === cell.id) {
        if (event.key === 'Escape') {
          event.preventDefault();
          event.stopPropagation();
          endEdit(cell.id, true);
        }
        // Let other keys work normally in input
        return;
      }

      const pos = getItemPosition(cell.id);
      if (!pos) return;

      const { rowIndex, colIndex } = pos;
      const { key, ctrlKey, shiftKey } = event;

      let handled = true;

      switch (key) {
        case 'ArrowRight': {
          if (shiftKey && enableRangeSelection) {
            const next = findNextFocusable(rowIndex, colIndex, 'right');
            if (next) {
              focusItem(next.id);
              extendRangeSelection(cell.id, next.id);
            }
          } else {
            const next = findNextFocusable(rowIndex, colIndex, 'right');
            if (next) {
              focusItem(next.id);
              setAnchorCellId(null);
            }
          }
          break;
        }
        case 'ArrowLeft': {
          if (shiftKey && enableRangeSelection) {
            const next = findNextFocusable(rowIndex, colIndex, 'left');
            if (next) {
              focusItem(next.id);
              extendRangeSelection(cell.id, next.id);
            }
          } else {
            const next = findNextFocusable(rowIndex, colIndex, 'left');
            if (next) {
              focusItem(next.id);
              setAnchorCellId(null);
            }
          }
          break;
        }
        case 'ArrowDown': {
          if (shiftKey && enableRangeSelection) {
            const next = findNextFocusable(rowIndex, colIndex, 'down');
            if (next) {
              focusItem(next.id);
              extendRangeSelection(cell.id, next.id);
            }
          } else {
            const next = findNextFocusable(rowIndex, colIndex, 'down');
            if (next) {
              focusItem(next.id);
              setAnchorCellId(null);
            }
          }
          break;
        }
        case 'ArrowUp': {
          if (shiftKey && enableRangeSelection) {
            const next = findNextFocusable(rowIndex, colIndex, 'up');
            if (next) {
              focusItem(next.id);
              extendRangeSelection(cell.id, next.id);
            }
          } else {
            const next = findNextFocusable(rowIndex, colIndex, 'up');
            if (next) {
              focusItem(next.id);
              setAnchorCellId(null);
            }
          }
          break;
        }
        case 'Home': {
          if (ctrlKey && shiftKey && enableRangeSelection) {
            // Ctrl+Shift+Home: extend selection to grid start
            const firstCell = rows[0]?.cells[0];
            if (firstCell) {
              focusItem(firstCell.id);
              extendRangeSelection(cell.id, firstCell.id);
            }
          } else if (ctrlKey) {
            // Ctrl+Home: Go to first cell in grid
            const firstCell = rows[0]?.cells[0];
            if (firstCell) {
              focusItem(firstCell.id);
              setAnchorCellId(null);
            }
          } else if (shiftKey && enableRangeSelection) {
            // Shift+Home: extend selection to row start
            const firstCellInRow = rows[rowIndex]?.cells[0];
            if (firstCellInRow) {
              focusItem(firstCellInRow.id);
              extendRangeSelection(cell.id, firstCellInRow.id);
            }
          } else {
            // Home: Go to first cell in row
            const firstCellInRow = rows[rowIndex]?.cells[0];
            if (firstCellInRow) {
              focusItem(firstCellInRow.id);
              setAnchorCellId(null);
            }
          }
          break;
        }
        case 'End': {
          const currentRow = rows[rowIndex];
          const lastRow = rows[rows.length - 1];

          if (ctrlKey && shiftKey && enableRangeSelection) {
            // Ctrl+Shift+End: extend selection to grid end
            const lastCell = lastRow?.cells[lastRow.cells.length - 1];
            if (lastCell) {
              focusItem(lastCell.id);
              extendRangeSelection(cell.id, lastCell.id);
            }
          } else if (ctrlKey) {
            // Ctrl+End: Go to last cell in grid
            const lastCell = lastRow?.cells[lastRow.cells.length - 1];
            if (lastCell) {
              focusItem(lastCell.id);
              setAnchorCellId(null);
            }
          } else if (shiftKey && enableRangeSelection) {
            // Shift+End: extend selection to row end
            const lastCellInRow = currentRow?.cells[currentRow.cells.length - 1];
            if (lastCellInRow) {
              focusItem(lastCellInRow.id);
              extendRangeSelection(cell.id, lastCellInRow.id);
            }
          } else {
            // End: Go to last cell in row
            const lastCellInRow = currentRow?.cells[currentRow.cells.length - 1];
            if (lastCellInRow) {
              focusItem(lastCellInRow.id);
              setAnchorCellId(null);
            }
          }
          break;
        }
        case 'PageDown': {
          if (enablePageNavigation) {
            const targetRowIndex = Math.min(rowIndex + pageSize, rows.length - 1);
            const targetCell = rows[targetRowIndex]?.cells[colIndex];
            if (targetCell) {
              focusItem(targetCell.id);
              setAnchorCellId(null);
            }
          } else {
            handled = false;
          }
          break;
        }
        case 'PageUp': {
          if (enablePageNavigation) {
            const targetRowIndex = Math.max(rowIndex - pageSize, 0);
            const targetCell = rows[targetRowIndex]?.cells[colIndex];
            if (targetCell) {
              focusItem(targetCell.id);
              setAnchorCellId(null);
            }
          } else {
            handled = false;
          }
          break;
        }
        case ' ': {
          if (selectable) {
            toggleSelection(cell.id, cell);
          }
          break;
        }
        case 'Enter': {
          if (editable && isCellEditable(cell, colId) && !cell.disabled) {
            startEdit(cell.id, rowId, colId);
          } else if (!cell.disabled) {
            onCellActivate?.(cell.id, rowId, colId);
          }
          break;
        }
        case 'F2': {
          if (editable && isCellEditable(cell, colId) && !cell.disabled) {
            startEdit(cell.id, rowId, colId);
          }
          break;
        }
        case 'a': {
          if (ctrlKey) {
            selectAll();
          } else {
            handled = false;
          }
          break;
        }
        default:
          handled = false;
      }

      if (handled) {
        event.preventDefault();
        event.stopPropagation();
      }
    },
    [
      editingCellId,
      endEdit,
      getItemPosition,
      findNextFocusable,
      focusItem,
      enableRangeSelection,
      extendRangeSelection,
      rows,
      enablePageNavigation,
      pageSize,
      selectable,
      toggleSelection,
      editable,
      isCellEditable,
      startEdit,
      onCellActivate,
      selectAll,
    ]
  );

  // ==========================================================================
  // Keyboard Handling - Checkbox Cell
  // ==========================================================================

  const handleCheckboxCellKeyDown = useCallback(
    (event: React.KeyboardEvent, rowId: string, row: DataGridRowData) => {
      const checkboxCellId = `checkbox-${rowId}`;
      const pos = getItemPosition(checkboxCellId);
      if (!pos) return;

      const { rowIndex, colIndex } = pos;
      const { key, ctrlKey } = event;

      let handled = true;

      switch (key) {
        case 'ArrowRight': {
          const next = findNextFocusable(rowIndex, colIndex, 'right');
          if (next) {
            focusItem(next.id);
          }
          break;
        }
        case 'ArrowLeft': {
          const next = findNextFocusable(rowIndex, colIndex, 'left');
          if (next) {
            focusItem(next.id);
          }
          break;
        }
        case 'ArrowDown': {
          const next = findNextFocusable(rowIndex, colIndex, 'down');
          if (next) {
            focusItem(next.id);
          }
          break;
        }
        case 'ArrowUp': {
          const next = findNextFocusable(rowIndex, colIndex, 'up');
          if (next) {
            focusItem(next.id);
          }
          break;
        }
        case 'Home': {
          if (ctrlKey) {
            // Ctrl+Home: Go to first cell in grid (first checkbox cell)
            const firstCheckboxId = `checkbox-${rows[0]?.id}`;
            if (firstCheckboxId) {
              focusItem(firstCheckboxId);
            }
          } else {
            // Home: Stay on checkbox (it's the first cell in the row)
            // Do nothing, already at home position
          }
          break;
        }
        case 'End': {
          const currentRow = rows[rowIndex];
          const lastRow = rows[rows.length - 1];

          if (ctrlKey) {
            // Ctrl+End: Go to last cell in grid
            const lastCell = lastRow?.cells[lastRow.cells.length - 1];
            if (lastCell) {
              focusItem(lastCell.id);
            }
          } else {
            // End: Go to last cell in row
            const lastCellInRow = currentRow?.cells[currentRow.cells.length - 1];
            if (lastCellInRow) {
              focusItem(lastCellInRow.id);
            }
          }
          break;
        }
        case ' ':
        case 'Enter': {
          // Toggle row selection
          if (!row.disabled) {
            toggleRowSelection(rowId, row);
          }
          break;
        }
        default:
          handled = false;
      }

      if (handled) {
        event.preventDefault();
        event.stopPropagation();
      }
    },
    [getItemPosition, findNextFocusable, focusItem, rows, toggleRowSelection]
  );

  // ==========================================================================
  // Effects
  // ==========================================================================

  // Focus input/select when entering edit mode
  useEffect(() => {
    if (editingCellId && editingColId) {
      const editType = getColumnEditType(editingColId);
      if (editType === 'select' && selectRef.current) {
        selectRef.current.focus();
      } else if (inputRef.current) {
        inputRef.current.focus();
        inputRef.current.select();
      }
    }
  }, [editingCellId, editingColId, getColumnEditType]);

  // Focus the focused cell when focusedId changes externally
  useEffect(() => {
    if (focusedId && !editingCellId) {
      const item = itemById.get(focusedId);
      if (item) {
        if (item.type === 'header') {
          const headerEl = headerRefs.current.get(item.columnId!);
          if (headerEl && document.activeElement !== headerEl) {
            if (gridRef.current?.contains(document.activeElement)) {
              headerEl.focus();
            }
          }
        } else {
          const cellEl = cellRefs.current.get(focusedId);
          if (cellEl && document.activeElement !== cellEl) {
            if (gridRef.current?.contains(document.activeElement)) {
              cellEl.focus();
            }
          }
        }
      }
    }
  }, [focusedId, editingCellId, itemById]);

  // ==========================================================================
  // Render
  // ==========================================================================

  // Determine aria-multiselectable
  const showMultiselectable = rowMultiselectable || multiselectable;

  // CSS variable for grid column count
  const gridStyle: Record<string, string | number> = {
    '--apg-data-grid-columns': columns.length,
  };

  return (
    <div
      ref={gridRef}
      role="grid"
      aria-label={ariaLabel}
      aria-labelledby={ariaLabelledby}
      aria-multiselectable={showMultiselectable ? 'true' : undefined}
      aria-readonly={readonly ? 'true' : undefined}
      aria-rowcount={totalRows}
      aria-colcount={totalColumns}
      className={`apg-data-grid ${className ?? ''}`}
      style={gridStyle}
    >
      {/* Header Row */}
      <div role="row" aria-rowindex={totalRows ? 1 : undefined}>
        {rowSelectable &&
          (() => {
            const isHeaderCheckboxFocused = focusedId === 'header-checkbox';
            return (
              <div
                ref={(el) => {
                  if (el) {
                    cellRefs.current.set('header-checkbox', el);
                  } else {
                    cellRefs.current.delete('header-checkbox');
                  }
                }}
                role="columnheader"
                tabIndex={rowMultiselectable ? (isHeaderCheckboxFocused ? 0 : -1) : undefined}
                aria-colindex={totalColumns ? startColIndex : undefined}
                className={`apg-data-grid-header apg-data-grid-checkbox-cell ${isHeaderCheckboxFocused ? 'focused' : ''}`}
                onKeyDown={rowMultiselectable ? handleHeaderCheckboxKeyDown : undefined}
                onFocus={() => rowMultiselectable && setFocusedId('header-checkbox')}
              >
                {rowMultiselectable && (
                  <input
                    type="checkbox"
                    tabIndex={-1}
                    checked={getSelectAllState() === 'all'}
                    ref={(el) => {
                      if (el) {
                        el.indeterminate = getSelectAllState() === 'some';
                      }
                    }}
                    aria-label="Select all rows"
                    onChange={(e) => {
                      e.stopPropagation();
                      toggleAllRowSelection();
                    }}
                  />
                )}
              </div>
            );
          })()}
        {columns.map((col, colIndex) => {
          const isSortable = col.sortable;
          const headerId = `header-${col.id}`;
          const isFocused = focusedId === headerId;

          return (
            <div
              key={col.id}
              ref={(el) => {
                if (el) {
                  headerRefs.current.set(col.id, el);
                } else {
                  headerRefs.current.delete(col.id);
                }
              }}
              role="columnheader"
              tabIndex={isSortable ? (isFocused ? 0 : -1) : undefined}
              aria-colindex={
                totalColumns ? startColIndex + colIndex + (rowSelectable ? 1 : 0) : undefined
              }
              aria-colspan={col.colspan}
              aria-sort={isSortable ? col.sortDirection || 'none' : undefined}
              onKeyDown={(e) => isSortable && handleHeaderKeyDown(e, col)}
              onFocus={() => isSortable && setFocusedId(headerId)}
              onClick={() => isSortable && handleSort(col.id)}
              className={`apg-data-grid-header ${isSortable ? 'sortable' : ''} ${isFocused ? 'focused' : ''}`}
            >
              {col.header}
              {isSortable && (
                <span
                  aria-hidden="true"
                  className={`sort-indicator ${!col.sortDirection || col.sortDirection === 'none' ? 'unsorted' : ''}`}
                >
                  {getSortIndicator(col.sortDirection)}
                </span>
              )}
            </div>
          );
        })}
      </div>

      {/* Data Rows */}
      {rows.map((row, rowIndex) => {
        const isRowSelected = selectedRowIds.includes(row.id);
        const isRowDisabled = row.disabled;

        return (
          <div
            key={row.id}
            role="row"
            aria-rowindex={totalRows ? startRowIndex + rowIndex : undefined}
            aria-selected={rowSelectable ? (isRowSelected ? 'true' : 'false') : undefined}
            aria-disabled={isRowDisabled ? 'true' : undefined}
          >
            {/* Row selection checkbox */}
            {rowSelectable &&
              (() => {
                const checkboxCellId = `checkbox-${row.id}`;
                const isCheckboxFocused = focusedId === checkboxCellId;
                return (
                  <div
                    ref={(el) => {
                      if (el) {
                        cellRefs.current.set(checkboxCellId, el);
                      } else {
                        cellRefs.current.delete(checkboxCellId);
                      }
                    }}
                    role="gridcell"
                    tabIndex={isCheckboxFocused ? 0 : -1}
                    aria-colindex={totalColumns ? startColIndex : undefined}
                    className={`apg-data-grid-cell apg-data-grid-checkbox-cell ${isCheckboxFocused ? 'focused' : ''}`}
                    onKeyDown={(e) => handleCheckboxCellKeyDown(e, row.id, row)}
                    onFocus={() => setFocusedId(checkboxCellId)}
                  >
                    <input
                      type="checkbox"
                      tabIndex={-1}
                      checked={isRowSelected}
                      disabled={isRowDisabled}
                      aria-labelledby={
                        rowLabelColumn ? `cell-${row.id}-${rowLabelColumn.id}` : undefined
                      }
                      onChange={(e) => {
                        e.stopPropagation();
                        toggleRowSelection(row.id, row);
                      }}
                    />
                  </div>
                );
              })()}

            {/* Data cells */}
            {row.cells.map((cell, colIndex) => {
              const isRowHeader = row.hasRowHeader && colIndex === 0;
              const cellId = cell.id;
              const isFocused = focusedId === cellId;
              const isCellSelected = selectedIds.includes(cellId);
              const colId = columns[colIndex]?.id ?? '';
              const isDisabled = cell.disabled || isRowDisabled;
              const isEditing = editingCellId === cellId;
              const cellIsEditable = editable && isCellEditable(cell, colId) && !isDisabled;
              const editType = getColumnEditType(colId);
              const columnOptions = getColumnOptions(colId);

              // Determine aria-readonly for this cell
              // APG: In editable grids, non-editable cells should have aria-readonly="true"
              const getAriaReadonly = (): 'true' | 'false' | undefined => {
                if (!editable) return undefined;
                if (cell.readonly === true) return 'true';
                if (cellIsEditable) return 'false';
                return 'true'; // Non-editable cell in editable grid
              };
              const showAriaReadonly = getAriaReadonly();

              // Generate id for label column cell to be referenced by row checkbox aria-labelledby
              const isLabelColumn = rowLabelColumn && colId === rowLabelColumn.id;
              const labelCellId = isLabelColumn ? `cell-${row.id}-${colId}` : undefined;

              // Unique IDs for combobox ARIA
              const comboboxListId = `${cellId}-listbox`;

              // Render edit content based on editType
              const renderEditContent = () => {
                if (editType === 'select') {
                  return (
                    <select
                      ref={selectRef}
                      value={editValue}
                      onChange={(e) => {
                        const newValue = e.target.value;
                        setEditValue(newValue);
                        onCellValueChange?.(cellId, newValue);
                        // End edit immediately with explicit value
                        endEdit(cellId, false, newValue);
                      }}
                      onBlur={() => endEdit(cellId, false)}
                      onKeyDown={(e) => {
                        if (e.key === 'Escape') {
                          e.preventDefault();
                          e.stopPropagation();
                          endEdit(cellId, true);
                        } else if (e.key === 'Enter') {
                          e.preventDefault();
                          e.stopPropagation();
                          endEdit(cellId, false);
                        }
                      }}
                      className="apg-data-grid-select"
                    >
                      {columnOptions.map((option) => (
                        <option key={option} value={option}>
                          {option}
                        </option>
                      ))}
                    </select>
                  );
                }

                if (editType === 'combobox') {
                  return (
                    <div className="apg-data-grid-combobox">
                      <input
                        ref={inputRef}
                        type="text"
                        role="combobox"
                        aria-expanded={comboboxExpanded}
                        aria-controls={comboboxListId}
                        aria-autocomplete="list"
                        aria-activedescendant={
                          comboboxActiveIndex >= 0
                            ? `${cellId}-option-${comboboxActiveIndex}`
                            : undefined
                        }
                        value={editValue}
                        onChange={(e) => {
                          const newValue = e.target.value;
                          setEditValue(newValue);
                          onCellValueChange?.(cellId, newValue);
                          // Filter options based on input
                          const filtered = columnOptions.filter((opt) =>
                            opt.toLowerCase().includes(newValue.toLowerCase())
                          );
                          setFilteredOptions(filtered);
                          setComboboxExpanded(true);
                          setComboboxActiveIndex(-1);
                        }}
                        onBlur={(e) => {
                          // Check if focus is moving to listbox
                          if (
                            e.relatedTarget instanceof Node &&
                            listboxRef.current?.contains(e.relatedTarget)
                          ) {
                            return;
                          }
                          setComboboxExpanded(false);
                          endEdit(cellId, false);
                        }}
                        onKeyDown={(e) => {
                          if (e.key === 'Escape') {
                            e.preventDefault();
                            e.stopPropagation();
                            setComboboxExpanded(false);
                            endEdit(cellId, true);
                          } else if (e.key === 'Enter') {
                            e.preventDefault();
                            e.stopPropagation();
                            const selectedOption =
                              comboboxActiveIndex >= 0
                                ? filteredOptions[comboboxActiveIndex]
                                : undefined;
                            if (selectedOption) {
                              setEditValue(selectedOption);
                              onCellValueChange?.(cellId, selectedOption);
                            }
                            setComboboxExpanded(false);
                            endEdit(cellId, false, selectedOption);
                          } else if (e.key === 'ArrowDown') {
                            e.preventDefault();
                            if (!comboboxExpanded) {
                              setComboboxExpanded(true);
                            } else {
                              setComboboxActiveIndex((prev) =>
                                Math.min(prev + 1, filteredOptions.length - 1)
                              );
                            }
                          } else if (e.key === 'ArrowUp') {
                            e.preventDefault();
                            setComboboxActiveIndex((prev) => Math.max(prev - 1, -1));
                          }
                        }}
                        className="apg-data-grid-input"
                      />
                      {comboboxExpanded && filteredOptions.length > 0 && (
                        <ul
                          ref={listboxRef}
                          id={comboboxListId}
                          role="listbox"
                          className="apg-data-grid-listbox"
                        >
                          {filteredOptions.map((option, index) => (
                            <li
                              key={option}
                              id={`${cellId}-option-${index}`}
                              role="option"
                              aria-selected={index === comboboxActiveIndex}
                              className={`apg-data-grid-option ${index === comboboxActiveIndex ? 'active' : ''}`}
                              onMouseDown={(e) => {
                                e.preventDefault();
                                setEditValue(option);
                                onCellValueChange?.(cellId, option);
                                setComboboxExpanded(false);
                                endEdit(cellId, false, option);
                              }}
                            >
                              {option}
                            </li>
                          ))}
                        </ul>
                      )}
                    </div>
                  );
                }

                // Default: text input
                return (
                  <input
                    ref={inputRef}
                    type="text"
                    value={editValue}
                    onChange={(e) => {
                      setEditValue(e.target.value);
                      onCellValueChange?.(cellId, e.target.value);
                    }}
                    onBlur={() => endEdit(cellId, false)}
                    onKeyDown={(e) => {
                      if (e.key === 'Escape') {
                        e.preventDefault();
                        e.stopPropagation();
                        endEdit(cellId, true);
                      } else if (e.key === 'Enter') {
                        e.preventDefault();
                        e.stopPropagation();
                        endEdit(cellId, false);
                      }
                    }}
                    className="apg-data-grid-input"
                  />
                );
              };

              return (
                <div
                  key={cellId}
                  id={labelCellId}
                  ref={(el) => {
                    if (el) {
                      cellRefs.current.set(cellId, el);
                    } else {
                      cellRefs.current.delete(cellId);
                    }
                  }}
                  role={isRowHeader ? 'rowheader' : 'gridcell'}
                  tabIndex={isFocused && !isEditing ? 0 : -1}
                  aria-selected={
                    selectable && !rowSelectable ? (isCellSelected ? 'true' : 'false') : undefined
                  }
                  aria-disabled={isDisabled ? 'true' : undefined}
                  aria-colindex={
                    totalColumns ? startColIndex + colIndex + (rowSelectable ? 1 : 0) : undefined
                  }
                  aria-colspan={cell.colspan}
                  aria-rowspan={cell.rowspan}
                  aria-readonly={showAriaReadonly}
                  onKeyDown={(e) => handleCellKeyDown(e, cell, row.id, colId)}
                  onFocus={() => !isEditing && setFocusedId(cellId)}
                  onDoubleClick={() => cellIsEditable && startEdit(cellId, row.id, colId)}
                  className={`apg-data-grid-cell ${isFocused ? 'focused' : ''} ${isCellSelected ? 'selected' : ''} ${isDisabled ? 'disabled' : ''} ${isEditing ? 'editing' : ''} ${cellIsEditable && !isEditing ? 'editable' : ''}`}
                >
                  {(() => {
                    if (isEditing) return renderEditContent();
                    if (renderCell) return renderCell(cell, row.id, colId);
                    return cell.value;
                  })()}
                </div>
              );
            })}
          </div>
        );
      })}
    </div>
  );
}

export default DataGrid;

使い方

使用例
import { DataGrid } from './DataGrid';
import type { DataGridColumnDef, DataGridRowData, SortDirection } from './DataGrid';

const columns: DataGridColumnDef[] = [
  { id: 'name', header: '名前', sortable: true },
  { id: 'email', header: 'メール', sortable: true },
  { id: 'role', header: '役割', sortable: true },
];

const rows: DataGridRowData[] = [
  {
    id: 'user1',
    cells: [
      { id: 'user1-name', value: '田中太郎', editable: true },
      { id: 'user1-email', value: 'tanaka@example.com', editable: true },
      { id: 'user1-role', value: '管理者' },
    ],
  },
  {
    id: 'user2',
    cells: [
      { id: 'user2-name', value: '鈴木花子', editable: true },
      { id: 'user2-email', value: 'suzuki@example.com', editable: true },
      { id: 'user2-role', value: 'ユーザー' },
    ],
  },
];

// 基本的な Data Grid(ソート付き)
<DataGrid
  columns={columns}
  rows={rows}
  ariaLabel="ユーザー一覧"
  onSort={(columnId, direction) => handleSort(columnId, direction)}
/>

// 行選択付き
<DataGrid
  columns={columns}
  rows={rows}
  ariaLabel="ユーザー一覧"
  rowSelectable
  rowMultiselectable
  selectedRowIds={selectedRowIds}
  onRowSelectionChange={(ids) => setSelectedRowIds(ids)}
/>

// 範囲選択と編集付き
<DataGrid
  columns={columns}
  rows={rows}
  ariaLabel="ユーザー一覧"
  enableRangeSelection
  editable
  onEditEnd={(cellId, value, cancelled) => {
    if (!cancelled) updateCell(cellId, value);
  }}
/>

API

DataGrid Props

Prop デフォルト 説明
columns DataGridColumnDef[] 必須 列定義
rows DataGridRowData[] 必須 行データ
ariaLabel string - グリッドのアクセシブルな名前
rowSelectable boolean false チェックボックスによる行選択を有効化
rowMultiselectable boolean false 複数行選択を有効化
onSort (columnId, direction) => void - ソートコールバック
enableRangeSelection boolean false Shift+矢印での範囲選択を有効化
editable boolean false セル編集を有効化
onEditEnd (cellId, value, cancelled) => void - 編集終了コールバック

型定義

Types
type SortDirection = 'ascending' | 'descending' | 'none' | 'other';

interface DataGridColumnDef {
  id: string;
  header: string;
  sortable?: boolean;
  sortDirection?: SortDirection;
}

interface DataGridCellData {
  id: string;
  value: string | number;
  disabled?: boolean;
  editable?: boolean;
  readonly?: boolean;
}

interface DataGridRowData {
  id: string;
  cells: DataGridCellData[];
  hasRowHeader?: boolean;
  disabled?: boolean;
}

テスト

テストは、キーボード操作、ARIA属性、アクセシビリティ要件全体のAPG準拠を検証します。データグリッドコンポーネントは、基本的なグリッドテスト戦略をソート、行選択、範囲選択、セル編集の追加テストで拡張しています。

テスト戦略

ユニットテスト(Testing Library)

フレームワーク固有のTesting Libraryユーティリティを使用して、コンポーネントのレンダリングとインタラクションを検証します。これらのテストは、分離された状態での正しいコンポーネントの動作を確認します。

  • HTML構造と要素階層(grid、row、gridcell)
  • 初期属性値(role、aria-label、tabindex、aria-sort)
  • 選択状態の変更(行とセルのaria-selected)
  • 編集モード状態(aria-readonly)
  • ソート方向の更新(aria-sort)
  • CSSクラスの適用

E2Eテスト(Playwright)

4つのフレームワークすべてにわたって実際のブラウザ環境でコンポーネントの動作を検証します。これらのテストは、完全なブラウザコンテキストを必要とするインタラクションをカバーします。

  • 2Dキーボードナビゲーション(矢印キー)
  • ヘッダーナビゲーションとソート
  • Shift+矢印による範囲選択
  • セル編集ワークフロー(Enter、F2、Escape)
  • チェックボックスによる行選択
  • ヘッダーとセル間のフォーカス管理
  • フレームワーク間の一貫性

テストカテゴリ

高優先度: APG ARIA属性

テスト 説明
role="grid" コンテナにgridロールがある
role="row" すべての行にrowロールがある
role="gridcell" データセルにgridcellロールがある
role="columnheader" ヘッダーセルにcolumnheaderロールがある
aria-sort ソート可能なヘッダーにaria-sortがある
aria-sort updates ソートアクションでaria-sortが更新される
aria-selected on rows rowSelectableの場合、行にaria-selectedがある
aria-readonly on grid readonlyプロップの場合、グリッドにaria-readonlyがある
aria-readonly on cells 編集可能性に基づいてセルにaria-readonlyがある
aria-multiselectable 行またはセルのマルチセレクトが有効な場合に存在

高優先度: ソート

テスト 説明
Enter on header ソート可能なヘッダーでEnterがソートをトリガー
Space on header ソート可能なヘッダーでSpaceがソートをトリガー
Sort cycle ソート循環: none → ascending → descending → ascending
Non-sortable headers ソート不可のヘッダーはEnter/Spaceに応答しない

高優先度: 範囲選択

テスト 説明
Shift+ArrowDown 選択を下に拡張
Shift+ArrowUp 選択を上に拡張
Shift+Home 選択を行の先頭まで拡張
Shift+End 選択を行の末尾まで拡張
Ctrl+Shift+Home 選択をグリッドの先頭まで拡張
Ctrl+Shift+End 選択をグリッドの末尾まで拡張
Selection anchor 最初の選択時に選択アンカーが設定される

高優先度: 行選択

テスト 説明
Checkbox toggle チェックボックスのクリックで行選択を切り替え
aria-selected 行要素でaria-selectedが更新される
Callback fires onRowSelectionChangeコールバックが発火
Select all 全選択チェックボックスがすべての行を選択/解除
Indeterminate 一部選択時に全選択が不確定状態を表示

高優先度: セル編集

テスト 説明
Enter starts edit 編集可能なセルでEnterが編集モードに入る
F2 starts edit 編集可能なセルでF2が編集モードに入る
Escape cancels Escapeが編集をキャンセルして元の値を復元
Navigation disabled 編集モード中はグリッドナビゲーションが無効
Focus on input 編集開始時にフォーカスが入力フィールドに移動
Focus returns 編集終了時にフォーカスがセルに戻る
onEditStart 編集モードに入るときにonEditStartコールバックが発火
onEditEnd 編集モードを終了するときにonEditEndコールバックが発火
Readonly cell 読み取り専用セルは編集モードに入らない

高優先度: フォーカス管理

テスト 説明
Sortable headers focusable ソート可能なヘッダーにtabindexがある
Non-sortable not focusable ソート不可のヘッダーにtabindexがない
First has tabindex=0 最初のフォーカス可能な要素にtabindex="0"がある
Header to data ヘッダーからArrowDownで最初のデータ行に入る
Data to header 最初の行からArrowUpでソート可能なヘッダーに入る
Roving tabindex ローヴィングタブインデックスが正しく更新される

中優先度: 仮想化サポート

テスト 説明
aria-rowcount totalRows提供時に存在(1ベース)
aria-colcount totalColumns提供時に存在(1ベース)
aria-rowindex 仮想化時に行に存在(1ベース)
aria-colindex 仮想化時にセルに存在(1ベース)

中優先度: アクセシビリティ

テスト 説明
axe-core アクセシビリティ違反なし
Sort indicators ソートインジケーターにアクセシブルな名前がある
Checkbox labels チェックボックスにアクセシブルなラベルがある

テストツール

testing-strategy.md (opens in new tab) を参照して完全なドキュメントをご覧ください。

リソース