@aiquants/directory-tree 3.0.5 → 3.1.1

package/src/DirectoryTree.spec.md

@@ -0,0 +1,473 @@
+# DirectoryTree Component Specification
+
+## 1. Revision History
+
+| Version | Date | Author | Reviewer | Approver | Summary of Changes |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| 3.0.1 | 2026-07-07 | Antigravity | | | Fix: `columns[0].className` is now correctly applied to the name column cells in the header and footer (TreeGrid mode), ensuring consistency with body rows and data columns. |
+| 3.0.0 | 2026-07-07 | Claude Opus 4.8 | | | Add TreeGrid (columns) mode via the optional `grid` prop (`DirectoryTreeGrid` / `DirectoryTreeColumn`). The name/tree column is frozen on the left (indent + connector lines confined there); the remaining columns render as a vertically-aligned grid with an aligned column header, an optional footer that aggregates over **all** entries (collapsed subtrees included), and a horizontally scrollable numeric region (the name column stays frozen). Grid mode uses `role="treegrid"` / `row` / `gridcell` / `columnheader`. Enabled by a new opt-in `onWheelHorizontal` prop on `@aiquants/virtualscroll` (axis-aware wheel). `grid` and each `render` / `footer` must be stable references. Note: connector lines are rendered on a `<canvas>` (this document previously described them as a single SVG component — corrected here). |
+| 2.2.0 | 2026-07-06 | Claude Opus 4.8 | | | Add `visual.itemHeight` (`number \| ((entry, index) => number)`, default 20) to make row height configurable. Variable-height rows are supported: the tree connector geometry and virtual-scroll range now use cumulative per-row offsets instead of a uniform pitch. Invalid values (`NaN` / `Infinity` / `0` / negative) fall back to 20px. |
+| 1.6 | 2026-06-15 | Antigravity | | | Add visual styling props (entryClassName, entryStyle, nameClassName, etc.) to allow custom css and inline styles for entries and name labels, eliminating downstream arbitrary selector hacks. |
+| 1.5 | 2025-11-10 | GitHub Copilot | | | Add showDirectoryIcons and showFileIcons props to control type icon visibility. |
+| 1.4 | 2025-11-10 | GitHub Copilot | | | Add showExpandIcons prop to toggle directory expand icon visibility. |
+| 1.3 | 2025-11-10 | GitHub Copilot | | | Add showTreeLines prop to allow toggling connector line rendering. |
+| 1.2 | 2025-09-12 | GitHub Copilot | | | Update lineColor prop to be configurable instead of using internal theme detection. Theme control moved to calling component. |
+| 1.1 | 2025-06-29 | GitHub Copilot | | | Add virtualization support using `useVirtualizer` hook. |
+| 1.0 | 2025-06-28 | Copilot | | | Newly created |
+
+## 2. Introduction
+
+### 2.1. Document Purpose
+
+This document provides the detailed design specifications for the `DirectoryTree` React component.
+本書は `DirectoryTree` React コンポーネントの詳細設計仕様書です。
+
+### 2.2. Background
+
+In applications that handle file and directory structures, there's a need for a UI component that can display hierarchical data efficiently. The previous implementation lacked performance with large datasets and had a rigid styling system.
+ファイルやディレクトリ構造を扱うアプリケーションでは、階層データを効率的に表示する UI コンポーネントが必要です。以前の実装は、大規模なデータセットに対するパフォーマンスが低く、柔軟性のないスタイリングシステムでした。
+
+### 2.3. Objective
+
+To provide a highly performant, customizable, and easy-to-use directory tree component. This component uses Tailwind CSS for flexible styling.
+パフォーマンスが高く、カスタマイズ可能で、使いやすいディレクトリツリーコンポーネントを提供することを目的とします。このコンポーネントは、Tailwind CSS を使用して柔軟なスタイリングを実現します。
+
+### 2.4. Scope
+
+#### 2.4.1. In Scope
+
+* Displaying a hierarchical directory structure based on the `DirectoryEntry` type.
+    `DirectoryEntry` 型に基づいた階層的なディレクトリ構造の表示。
+* Expanding and collapsing individual directories.
+    個々のディレクトリの展開と折りたたみ。
+* Recursively expanding and collapsing a directory and its children (e.g., via double-click).
+    ディレクトリとその子要素の再帰的な展開と折りたたみ (例: ダブルクリック)。
+* File selection callback.
+    ファイル選択時のコールバック機能。
+* Customizable styling via `className` and `style` props.
+    `className` および `style` props を介したカスタマイズ可能なスタイリング。
+* Persisting the expansion state of each entity in `localStorage`.
+    `localStorage` に各エンティティの展開状態を保存して維持する。
+* Explicitly handling `absolutePath` and `relativePath` within the `DirectoryTree`.
+    `DirectoryTree` 内部で `absolutePath` と `relativePath` を明示的に扱う。
+* Improving user experience by using `startTransition` for state management of expansion.
+    展開状態の管理に `startTransition` を用いてUXを向上させる。
+* Rendering tree connector lines on a `<canvas>` overlay to visually represent the hierarchy and the open/closed state of directories.
+    `<canvas>` オーバーレイにツリー接続線を描画し、ディレクトリの階層と開閉状態を視覚的に表現する。
+* Virtualization of directory items for improved performance with large directories (via `@aiquants/virtualscroll`).
+    ディレクトリアイテムの仮想化により、大規模なディレクトリでのパフォーマンスを向上させる（`@aiquants/virtualscroll` を使用）。
+* TreeGrid (columns) mode: a frozen name/tree column plus vertically-aligned data columns with an aligned header, an optional all-entries footer, and a horizontally scrollable numeric region — enabled via the optional `grid` prop.
+    TreeGrid（列）モード: 凍結した名前/ツリー列と縦整列したデータ列、整列ヘッダ、任意の全 entries フッタ、数値領域の横スクロールを、任意の `grid` prop で提供する。
+
+#### 2.4.2. Out of Scope
+
+* File operations (create, delete, rename).
+    ファイル操作 (作成、削除、名前変更)。
+* Drag-and-drop functionality.
+    ドラッグアンドドロップ機能。
+* Context menu integration.
+    コンテキストメニューの統合。
+
+#### 2.4.3. Future Expansion (Optional)
+
+* Integration with a file system API to dynamically load directory contents.
+    ファイルシステム API と統合し、ディレクトリの内容を動的に読み込む機能。
+* Support for custom icons based on file type or directory state.
+    ファイルタイプやディレクトリの状態に応じたカスタムアイコンのサポート。
+
+### 2.5. Target Audience
+
+This document is intended for developers who will use or contribute to the `DirectoryTree` component, as well as UI/UX designers who need to understand its capabilities.
+本書は `DirectoryTree` コンポーネントを使用または開発に貢献する開発者、およびその機能を理解する必要がある UI/UX デザイナーを対象としています。
+
+### 2.6. References
+
+* `DirectoryEntry` type definition: [DirectoryTree.tsx](./DirectoryTree.tsx)
+* `useDirectoryTreeState` hook: [useDirectoryTreeState.ts](./useDirectoryTreeState.ts)
+* `TreeLine` component: [TreeLine.tsx](./TreeLine.tsx)
+
+### 2.7. Prerequisites and Constraints
+
+* The component must be used within a React application.
+    コンポーネントは React アプリケーション内で使用する必要があります。
+* Styling is managed via Tailwind CSS and `tailwind-variants`. Proper configuration of Tailwind CSS is required.
+    スタイリングは Tailwind CSS と `tailwind-variants` を介して管理されます。Tailwind CSS の適切な設定が必要です。
+* Input data must conform to the `DirectoryEntry[]` type structure.
+    入力データは `DirectoryEntry[]` 型の構造に準拠する必要があります。
+
+### 2.8. Architectural Policy and Technology Selection
+
+* **State Management**: The expansion state of the tree is managed by the `useDirectoryTreeState` hook, separating state logic from the presentation component.
+    **状態管理**: ツリーの展開状態は `useDirectoryTreeState` フックによって管理され、状態ロジックをプレゼンテーションコンポーネントから分離します。
+* **Styling**: `tailwind-variants` is used for creating a flexible and customizable styling system based on component state and props.
+    **スタイリング**: `tailwind-variants` を使用して、コンポーネントの状態と Props に基づいた柔軟でカスタマイズ可能なスタイリングシステムを構築します。
+* **Componentization**: The component is broken down into smaller, manageable parts like `DirectoryEntryItem` and `TreeLine` to improve maintainability and reusability.
+    **コンポーネント化**: コンポーネントは `DirectoryEntryItem` や `TreeLine` のような小さく管理しやすいパーツに分割され、保守性と再利用性を向上させています。
+
+## 3. Component API
+
+### 3.1. Data Structures
+
+#### 3.1.1. `DirectoryEntry`
+
+The fundamental data structure for representing a file or directory.
+ファイルまたはディレクトリを表す基本的なデータ構造。
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `name` | `string` | The name of the file or directory. ファイルまたはディレクトリの名前。 |
+| `absolutePath` | `string` | The absolute path of the entry. エントリの絶対パス。 |
+| `relativePath` | `string` | The path of the entry relative to the root. ルートからの相対パス。 |
+| `children` | `DirectoryEntry[] \| null` | An array of child entries if it's a directory, otherwise `null`. ディレクトリの場合は子エントリの配列、それ以外の場合は `null`。 |
+
+### 3.2. Props
+
+The `DirectoryTree` component accepts the following props:
+`DirectoryTree` コンポーネントは、以下の props を受け入れます。
+
+| Prop Name | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `entries` | `DirectoryEntry[]` | Yes | - | The array of root directory entries to display. 表示するルートディレクトリのエントリの配列。 |
+| `expansion` | `object` | Yes | - | Configuration for tree expansion state and behavior. ツリーの展開状態と動作の設定。 |
+| `selection` | `object` | Yes | - | Configuration for item selection. アイテム選択の設定。 |
+| `visual` | `object` | No | - | Visual customization options. 表示のカスタマイズオプション。 |
+| `virtualScroll` | `DirectoryTreeVirtualScrollOptions` | No | - | Additional options for VirtualScroll integration. VirtualScroll の設定を上書きするオプション。 |
+| `grid` | `DirectoryTreeGrid` | No | - | TreeGrid (columns) mode. When present, renders a frozen name column + aligned data columns with header/footer and a horizontally scrollable numeric region. See §3.2.4. TreeGrid（列）モード。指定時は凍結名前列＋整列データ列を描画する（§3.2.4）。 |
+
+#### 3.2.1. `expansion` Configuration
+
+| Property | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `toggle` | `(path: string) => void` | Yes | - | Function to toggle directory expansion state. ディレクトリの展開状態を切り替える関数。 |
+| `isExpanded` | `(path: string) => boolean` | Yes | - | Function to check if a directory is expanded. ディレクトリが展開されているかを確認する関数。 |
+| `expandMultiple` | `(paths: string[]) => void` | Yes | - | Function to expand multiple directories. 複数のディレクトリを展開する関数。 |
+| `collapseMultiple` | `(paths: string[]) => void` | Yes | - | Function to collapse multiple directories. 複数のディレクトリを折りたたむ関数。 |
+| `isPending` | `boolean` | No | `false` | Whether the tree is in a pending state. ツリーが保留状態かどうか。 |
+| `alwaysExpanded` | `boolean` | No | `false` | If true, all directories are always expanded. true の場合、すべてのディレクトリが常に展開されます。 |
+| `doubleClickAction` | `'recursive' \| 'toggle'` | No | `'recursive'` | Action on double-clicking a directory. ディレクトリをダブルクリックしたときのアクション。 |
+
+#### 3.2.2. `selection` Configuration
+
+| Property | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `onEntryClick` | `(event: DirectoryTreeClickEvent) => void` | Yes | - | Callback triggered when an entry is clicked. エントリがクリックされたときのコールバック。 |
+| `selectedPath` | `string \| null` | No | - | The currently selected path. 現在選択されているパス。 |
+| `mode` | `'none' \| 'single' \| 'multiple'` | No | `'none'` | Selection mode for items. アイテムの選択モード。 |
+| `selectedItems` | `Set<string>` | No | - | Set of paths for currently selected items. 現在選択されているアイテムのパスのセット。 |
+| `onSelectionChange` | `(entry: DirectoryEntry, isSelected: boolean) => void` | No | - | Callback when item selection changes. アイテム選択状態変更時のコールバック。 |
+
+#### 3.2.3. `visual` Configuration
+
+| Property | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `className` | `string` | No | - | Additional CSS classes to apply to the root container. コンテナ用のオプション CSS クラス名。 |
+| `style` | `React.CSSProperties` | No | - | Inline styles to apply to the root container. コンテナ用のオプションのインラインスタイル。 |
+| `lineColor` | `string` | No | `'#A0AEC0'` | The color of the tree lines. ツリーラインの色。 |
+| `showTreeLines` | `boolean` | No | `true` | Whether to render connector tree lines. ツリーのコネクタラインを描画するかどうか。 |
+| `showExpandIcons` | `boolean` | No | `true` | Whether to render directory expand icons. ディレクトリの展開アイコンを描画するかどうか。 |
+| `showDirectoryIcons` | `boolean` | No | `true` | Whether to render directory type icons. ディレクトリアイコンを描画するかどうか。 |
+| `showFileIcons` | `boolean` | No | `true` | Whether to render file type icons. ファイルアイコンを描画するかどうか。 |
+| `iconOverrides` | `DirectoryTreeIconOverrides` | No | - | Icon overrides applied globally. グローバルに適用するアイコン差し替え設定。 |
+| `expandIconSize` | `number` | No | - | Size of the expand icon. 展開アイコンのサイズ。 |
+| `itemHeight` | `number \| ((entry, index) => number)` | No | `20` | Row height in px, or a function computing the height per entry (variable-height rows). Tree connector lines follow each row's cumulative offset. Invalid values (`NaN` / `Infinity` / `0` / negative) fall back to `20`. Memoize the function to keep its identity stable. 各行の高さ (px)、またはエントリごとに高さを算出する関数（可変高さ行）。ツリー接続線は各行の累積オフセットに追従する。不正値（`NaN` / `Infinity` / `0` / 負値）は `20` にフォールバックする。関数は identity を安定させること。 |
+| `removeRootIndent` | `boolean` | No | `false` | If true, removes indentation for root-level items. ルートレベルのアイテムのインデントを削除するかどうか。 |
+| `highlightStyles` | `HighlightStyles` | No | - | Custom hover and selection styles. ホバー時および選択時のカスタムスタイル。 |
+| `entryClassName` | `string` | No | - | Additional CSS classes for each entry row. 各エントリ（行）に適用する追加の CSS クラス名。 |
+| `entryStyle` | `React.CSSProperties` | No | - | Additional inline styles for each entry row. 各エントリ（行）に適用する追加のインラインスタイル。 |
+| `nameClassName` | `string` | No | - | Additional CSS classes for the name label. 名前（ラベル）部分に適用する追加の CSS クラス名。 |
+| `nameStyle` | `React.CSSProperties` | No | - | Additional inline styles for the name label. 名前（ラベル）部分に適用する追加のインラインスタイル。 |
+| `directoryNameClassName` | `string` | No | - | Additional CSS classes specifically for directory names. ディレクトリ名特有の追加の CSS クラス名。 |
+| `directoryNameStyle` | `React.CSSProperties` | No | - | Additional inline styles specifically for directory names. ディレクトリ名特有の追加のインラインスタイル。 |
+| `fileNameClassName` | `string` | No | - | Additional CSS classes specifically for file names. ファイル名特有の追加の CSS クラス名。 |
+| `fileNameStyle` | `React.CSSProperties` | No | - | Additional inline styles specifically for file names. ファイル名特有の追加のインラインスタイル。 |
+
+#### 3.2.4. `grid` Configuration (TreeGrid columns mode)
+
+When `grid` is provided, the tree renders as a **TreeGrid**: the name/tree column is frozen on the left
+(indentation and connector lines stay confined there) while the remaining columns render as a
+vertically-aligned grid — with an aligned column header, an optional footer aggregating over **all**
+entries, and a horizontally scrollable numeric region. When omitted, the classic label tree is rendered.
+`grid` 指定時は TreeGrid として描画する（凍結名前列＋整列データ列＋整列ヘッダ/フッタ＋数値領域横スクロール）。省略時は従来のラベルツリー。
+
+`DirectoryTreeGrid`:
+
+| Property | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `columns` | `DirectoryTreeColumn[]` | Yes | - | Column definitions (**stable reference required**). `columns[0]` is always the name/tree column. 列定義（参照安定必須）。`columns[0]` が名前/ツリー列。 |
+| `showHeader` | `boolean` | No | `true` | Render the aligned column header row. 整列した列ヘッダ行を描画するか。 |
+| `showFooter` | `boolean` | No | `false` | Render the footer row (aggregates over all entries). フッタ行（全 entries 集計）を描画するか。 |
+| `headerClassName` | `string` | No | - | Extra class for the header row. ヘッダ行の追加クラス。 |
+| `footerClassName` | `string` | No | - | Extra class for the footer row. フッタ行の追加クラス。 |
+| `rowClassName` | `string \| ((entry) => string)` | No | - | Extra class (or per-entry factory) for body rows. 行の追加クラス（またはエントリ別ファクトリ）。 |
+| `scrollBarWidth` | `number` | No | `virtualScroll.scrollBarOptions.width ?? 12` | Vertical scrollbar width used to align the header/footer numeric viewport with the body. 縦バー幅（ヘッダ/フッタと本体の数値ビューポート整合に使用）。 |
+
+`DirectoryTreeColumn`:
+
+| Property | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `key` | `string` | Yes | - | Unique column key. 一意なキー。 |
+| `header` | `ReactNode` | No | - | Column header content. 列ヘッダ内容。 |
+| `footer` | `ReactNode \| ((allEntries: DirectoryEntry[]) => ReactNode)` | No | - | Footer content. The function form receives **every node of `entries` (collapsed subtrees included)**. フッタ内容。関数形は entries の全ノード（折り畳み含む）を受け取る。 |
+| `width` | `number` | No | `240` (name) / `96` (data) | Column width in px (name column = frozen width; data column = grid track). 列幅 (px)。 |
+| `align` | `'left' \| 'right' \| 'center'` | No | `'left'` | Cell alignment. セル寄せ。 |
+| `className` | `string` | No | - | Extra class for this column's cells. この列のセルの追加クラス。 |
+| `render` | `(entry, ctx: { indentLevel; isDirectory; isExpanded }) => ReactNode` | No* | - | Cell renderer. In the name column, indent/glyph/icon are drawn by the library and this output is the label (falls back to `entry.label ?? entry.name`). *Required for data columns. セル描画。名前列では indent/glyph/icon はライブラリが描画。 |
+
+**Rendering rules / behavior:**
+
+1. Indentation, the expand glyph, and the type icon are applied to the **name cell only**; data cells carry no per-depth offset, so numeric columns align across the whole hierarchy.
+2. The name column is **frozen** at `x=0`; only the data region scrolls horizontally, driven by the `--dt-hscroll` CSS variable shared by the header, every body row, and the footer (so they stay aligned).
+3. The header/body/footer numeric viewport width all resolve to `measuredWidth − nameWidth − scrollBarWidth`; `grid.scrollBarWidth` defaults to the actual VirtualScroll scrollbar width so columns stay aligned even when it is customized.
+4. Grid mode uses `role="treegrid"` / `row` / `gridcell` / `columnheader`; `aria-expanded` / `aria-level` are set on the row.
+5. `grid.columns` and each `render` / `footer` **must be stable references** (memoize them) — otherwise every visible row re-renders.
+6. `visual.removeRootIndent` is **ignored in grid mode** (the frozen name column must start at `x=0`).
+7. With empty `entries`, grid mode still renders the header and footer (footer aggregates over 0 entries) with the `treegrid` role; only the body has no rows.
+8. Horizontal scrolling only updates the shared CSS variable — the virtualized body is **not** re-rendered (the `VirtualScroll` element is memoized and the rows are `React.memo`-skipped).
+
+### 3.3. Usage
+
+Here is a basic example of how to use the `DirectoryTree` component with the `useDirectoryTreeState` hook.
+これは `DirectoryTree` コンポーネントを `useDirectoryTreeState` フックと共に使用する基本的な使用例です。
+
+**Note:** This component is designed to be used with the `useDirectoryTreeState` hook to manage the expansion state. The `lineColor` can be controlled based on the current theme.
+**注:** このコンポーネントは、展開状態を管理するために `useDirectoryTreeState` フックと共に使用するように設計されています。`lineColor` は現在のテーマに基づいて制御できます。
+
+```tsx
+import React, { useState } from 'react'
+import { DirectoryTree, DirectoryEntry } from './DirectoryTree' // Adjust the import path
+import { useDirectoryTreeState } from './useDirectoryTreeState' // Adjust the import path
+import { useTheme } from './useTheme' // Adjust the import path
+
+const sampleEntries: DirectoryEntry[] = [
+    {
+        name: 'src',
+        absolutePath: '/src',
+        relativePath: 'src',
+        children: [
+            {
+                name: 'components',
+                absolutePath: '/src/components',
+                relativePath: 'src/components',
+                children: [
+                    {
+                        name: 'Button.tsx',
+                        absolutePath: '/src/components/Button.tsx',
+                        relativePath: 'src/components/Button.tsx',
+                        children: null,
+                    },
+                ],
+            },
+            {
+                name: 'App.tsx',
+                absolutePath: '/src/App.tsx',
+                relativePath: 'src/App.tsx',
+                children: null,
+            },
+        ],
+    },
+    {
+        name: 'package.json',
+        absolutePath: '/package.json',
+        relativePath: 'package.json',
+        children: null,
+    },
+]
+
+const App = () => {
+    const [selectedFile, setSelectedFile] = useState<string | null>(null)
+    const { theme } = useTheme()
+    const treeState = useDirectoryTreeState({
+        storageKey: 'my-tree-state',
+    })
+
+    // Calculate line color based on theme
+    const lineColor = theme === "dark" ? "#4A5568" : "#A0AEC0"
+
+    const handleEntryClick = (event: DirectoryTreeClickEvent) => {
+        console.log(`Entry clicked: ${event.entry.absolutePath}`)
+        setSelectedFile(event.entry.absolutePath)
+    }
+
+    return (
+        <div style={{ width: '300px', height: '500px', border: '1px solid #ccc' }}>
+            <DirectoryTree
+                entries={sampleEntries}
+                onEntryClick={handleEntryClick}
+                selectedPath={selectedFile}
+                toggle={treeState.toggle}
+                isExpanded={treeState.isExpanded}
+                expandMultiple={treeState.expandMultiple}
+                collapseMultiple={treeState.collapseMultiple}
+                isPending={treeState.isPending}
+                lineColor={lineColor}
+            />
+            {selectedFile && <p>Selected file: {selectedFile}</p>}
+        </div>
+    )
+}
+            />
+            {selectedFile && <p>Selected file: {selectedFile}</p>}
+        </div>
+    )
+}
+
+export default App
+```
+
+## 4. Internal Hooks
+
+This section describes the hooks used internally by the `DirectoryTree` component.
+このセクションでは、`DirectoryTree` コンポーネントが内部で使用するフックについて説明します。
+
+### 4.1. `useDirectoryTreeState`
+
+#### 4.1.1. Overview
+
+This hook manages the expansion state of the directory tree. It persists the state to `localStorage` to maintain it across sessions and uses `useTransition` to perform state updates without blocking the UI.
+このフックは、ディレクトリツリーの展開状態を管理します。状態を `localStorage` に永続化してセッション間で維持し、`useTransition` を使用して UI をブロックせずに状態更新を実行します。
+
+#### 4.1.2. Input (Options)
+
+| Prop Name | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `initialEntries` | `DirectoryEntry[]` | No | `[]` | The initial set of directory entries. Used to determine the default expansion state if no state is found in `localStorage`. 初期ディレクトリ エントリのセット。`localStorage` に状態が見つからない場合に、デフォルトの展開状態を決定するために使用されます。 |
+| `storageKey` | `string` | No | `directory-tree-state` | The key used to store the expansion state in `localStorage`. 展開状態を `localStorage` に保存するために使用されるキー。 |
+
+#### 4.1.3. Output
+
+The hook returns a `DirectoryTreeState` object with the following properties:
+このフックは、次のプロパティを持つ `DirectoryTreeState` オブジェクトを返します。
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `expanded` | `Set<string>` | A set of absolute paths of the expanded directories. 展開されているディレクトリの絶対パスのセット。 |
+| `toggle` | `(path: string) => void` | Function to toggle the expansion state of a directory. ディレクトリの展開状態を切り替える関数。 |
+| `expand` | `(path: string) => void` | Function to expand a directory. ディレクトリを展開する関数。 |
+| `collapse` | `(path: string) => void` | Function to collapse a directory. ディレクトリを折りたたむ関数。 |
+| `collapseMultiple` | `(paths: string[]) => void` | Function to collapse multiple directories. 複数のディレクトリを折りたたむ関数。 |
+| `expandMultiple` | `(paths: string[]) => void` | Function to expand multiple directories. 複数のディレクトリを展開する関数。 |
+| `isPending` | `boolean` | A flag that is true when a state transition is pending. 状態遷移が保留中の場合に true となるフラグ。 |
+
+## 5. Data Structures
+
+### 5.1. `DirectoryEntry`
+
+This type represents a single node in the directory tree.
+この型は、ディレクトリツリー内の単一ノードを表します。
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `name` | `string` | The name of the file or directory. ファイルまたはディレクトリの名前。 |
+| `type` | `"file" \| "directory"` | The type of the entry. エントリの種別。 |
+| `absolutePath` | `string` | The absolute path of the entry. エントリの絶対パス。 |
+| `relativePath` | `string` | The relative path of the entry. エントリの相対パス。 |
+| `children` | `DirectoryEntry[] \| undefined` | An array of child entries if the type is `directory`. `type` が `directory` の場合の子エントリの配列。 |
+
+### 5.2. `DirectoryTreeState`
+
+This type represents the state object managed by the `useDirectoryTreeState` hook.
+この型は `useDirectoryTreeState` フックによって管理される状態オブジェクトを表します。
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `expanded` | `Set<string>` | A set of absolute paths of the expanded directories. 展開されているディレクトリの絶対パスのセット。 |
+| `toggle` | `(path: string) => void` | Function to toggle the expansion state of a directory. ディレクトリの展開状態を切り替える関数。 |
+| `expand` | `(path: string) => void` | Function to expand a directory. ディレクトリを展開する関数。 |
+| `collapse` | `(path: string) => void` | Function to collapse a directory. ディレクトリを折りたたむ関数。 |
+| `collapseMultiple` | `(paths: string[]) => void` | Function to collapse multiple directories. 複数のディレクトリを折りたたむ関数。 |
+| `expandMultiple` | `(paths: string[]) => void` | Function to expand multiple directories. 複数のディレクトリを展開する関数。 |
+| `isPending` | `boolean` | A flag that is true when a state transition is pending. 状態遷移が保留中の場合に true となるフラグ。 |
+
+## 6. Functional Requirements
+
+### 6.1. Directory Expansion and Collapse
+
+* **Single Click**: A single click on a directory icon or name toggles its expansion state (expanded or collapsed).
+* **Double Click**: A double click on a directory can trigger one of two behaviors, selectable via a prop:
+    1. Toggle the expansion state of all descendant directories.
+    2. Recursively expand or collapse the directory and all its subdirectories.
+* **シングルクリック**: ディレクトリのアイコンまたは名前をシングルクリックすると、その展開状態 (展開または折りたたみ) が切り替わります。
+* **ダブルクリック**: ディレクトリをダブルクリックすると、プロパティを介して選択可能な 2 つの動作のいずれかがトリガーされます。
+    1. すべての子孫ディレクトリの展開状態を切り替える。
+    2. ディレクトリとそのすべてのサブディレクトリを再帰的に展開または折りたたむ。
+
+### 6.2. File Selection
+
+* A single click on a file name triggers the `onEntryClick` callback, passing a `DirectoryTreeClickEvent` containing the entry and metadata.
+* The selected file is highlighted.
+* ファイル名をクリックすると `onEntryClick` コールバックがトリガーされ、エントリとメタデータを含む `DirectoryTreeClickEvent` が渡されます。
+* 選択されたファイルがハイライト表示されます。
+
+## 7. Non-Functional Requirements
+
+### 7.1. Performance
+
+* The component must render efficiently, even with a large number of files and directories.
+* `React.memo` should be used for `DirectoryEntryItem` to prevent unnecessary re-renders.
+* The `useDirectoryTreeState` hook will use `useTransition` to prevent UI blocking during state updates, improving the user experience.
+* In grid mode, the `VirtualScroll` element is memoized so a horizontal-scroll tick (which only changes the `--dt-hscroll` variable) does not re-render the virtualized body; both `DirectoryEntryItem` and `DirectoryTreeGridRow` are `React.memo`-guarded.
+* 多数のファイルやディレクトリがあっても、コンポーネントは効率的にレンダリングされる必要があります。
+* 不要な再レンダリングを防ぐために、`DirectoryEntryItem` には `React.memo` を使用する必要があります。
+* grid モードでは `VirtualScroll` 要素をメモ化し、横スクロール（`--dt-hscroll` 変数のみ変化）で仮想化本体を再レンダーしない。`DirectoryEntryItem` / `DirectoryTreeGridRow` はいずれも `React.memo` 対象。
+* `useDirectoryTreeState` フックは `useTransition` を使用して、状態更新中の UI ブロッキングを防ぎ、ユーザーエクスペリエンスを向上させます。
+
+### 7.2. Styling
+
+* The component is styled using Tailwind CSS for flexibility.
+* The color and width of the tree lines are customizable via props.
+* コンポーネントは、柔軟性のために Tailwind CSS を使用してスタイリングされます。
+* ツリーラインの色と幅は、プロパティを介してカスタマイズ可能です。
+
+## 8. Dependencies
+
+* `react` / `react-dom` (peer dependencies)
+* `@aiquants/virtualscroll` (virtual scrolling engine; also provides the horizontal `ScrollBar` and `onWheelHorizontal`)
+* `@heroicons/react`, `@phosphor-icons/react` (default type / expand icons)
+* `tailwind-merge` (class-name merging)
+* Tailwind CSS v4 (styling)
+
+## 9. Test Specification
+
+The package ships a comprehensive Vitest suite. Coverage is **100% (statements / functions / lines)** on the
+new TreeGrid modules (`gridUtils.ts`, `useEntryInteraction.ts`, `entryRendering.tsx`, `DirectoryTreeGrid.tsx`)
+and 100% statements/functions/lines on `DirectoryTree.tsx` (residual branches are defensive null-safety/dedup
+guards). Run `pnpm run test:coverage`.
+
+### 9.1. Classic tree ([DirectoryTree.test.tsx](../tests/DirectoryTree.test.tsx))
+
+* **Basic Rendering**: the file/directory hierarchy renders (file name, expanding directories, etc.).
+* **Selection Action**: clicking a file triggers the selection callbacks (`onEntryClick`) with correct parameters.
+* **Custom Styling**: highlight class names (`directorySelectedClassName` / `itemSelectedClassName`) and styles are applied to active entries.
+* **Hover Interaction**: custom hover styling (`hoverClassName` / `hoverStyle`) is applied on mouse enter.
+* **Entry-specific Custom Styling**: entry (`entryClassName`/`entryStyle`) and name (`nameClassName`/`nameStyle`, `directoryNameClassName`/`directoryNameStyle`, `fileNameClassName`/`fileNameStyle`) classes/styles are merged and applied.
+
+### 9.2. Behavior ([DirectoryTree.behavior.test.tsx](../tests/DirectoryTree.behavior.test.tsx))
+
+* **Interaction**: plain-row `onMouseLeave` / `onKeyDown(Enter)`; double-click actions (`expandMultiple` on all-collapsed, `collapseMultiple` on all-expanded, `collapseMultiple` on mixed+toggle).
+* **removeRootIndent / empty entries**: root indent removal renders without error; empty `entries` renders the placeholder container only.
+* **Tree-line geometry render**: an expanded tree with `viewportHeightOverride` + `showTreeLines` paints the connector canvas.
+* **Scroll callbacks**: vertical wheel drives `handleVirtualScroll` / `handleRangeChange`.
+* **Plain-row style branches**: selected file / itemSelected / directory selection (default & override); icon-hidden; `initialScrollOffset`; entry-reference-change re-render.
+* **Grid horizontal wiring**: horizontal wheel advances `--dt-hscroll`; the horizontal `ScrollBar` `onScroll` updates hscroll; `scrollBarOptions.width` is reflected in the header spacer; **rows are not re-rendered on horizontal scroll** (memoization guard).
+
+### 9.3. TreeGrid mode ([DirectoryTreeGrid.test.tsx](../tests/DirectoryTreeGrid.test.tsx))
+
+* **Semantics**: `role="treegrid"` when `grid` is set, `role="tree"` otherwise; aligned column headers.
+* **Alignment invariant**: name cells indent by depth (`0/16/32px`); data cells carry **no** per-depth padding.
+* **ClassName consistency**: verifies that `columns[i].className` is applied to body, header, and footer cells for both the name column and numeric columns.
+* **Footer**: `showFooter` aggregates over all entries (collapsed subtrees included); function and `ReactNode` footer forms.
+* **Row states**: selection (`selectedPath` / `selectedItems`), highlight classes/styles, hover, `align=center`, `rowClassName` factory, custom / fallback name render, name-only columns, empty data cell.
+* **removeRootIndent ignored in grid** (normal `0/16px` indent preserved); **empty grid** still renders header/footer/`treegrid` role.
+* **Memo comparator** (`isEntryExpanded`, entry-reference change, directory expansion change).
+* **`isEntryExpanded`** helper: directory expanded/collapsed, file short-circuit.
+
+### 9.4. Pure helpers
+
+* **[gridUtils.test.ts](../tests/gridUtils.test.ts)**: `buildNumericTemplate`, `computeGridMetrics`, `clampHScroll`, `flattenAllEntries` (incl. default/invalid widths, zero-width viewport, NaN clamp).
+* **[treeLineGeometry.test.ts](../tests/treeLineGeometry.test.ts)**: `buildTreeLineGeometry` — every connector variant (directory/file, last-child, ancestor lines, glyphs), `hideLines` skip, empty input, glyph-size fallback, and defensive out-of-bounds fallbacks.
+* **[useEntryInteraction.test.tsx](../tests/useEntryInteraction.test.tsx)**: file select, directory single-click (delayed toggle), double-click (recursive), `preventDefault`, unmount timer cleanup.
+* **[entryRendering.test.tsx](../tests/entryRendering.test.tsx)**: `resolveExpandIcon`, `resolveEntryIcon` (all icon paths + sanitizer edge cases), `getFileExtension`.
+
+### 9.5. VirtualScroll horizontal wheel (`@aiquants/virtualscroll`)
+
+* **[wheel-horizontal.spec.tsx](../../virtualscroll/tests/integration/wheel-horizontal.spec.tsx)**: `onWheelHorizontal` fires on horizontal-dominant / shift+wheel gestures, not on vertical-dominant; `deltaMode` LINE/PAGE scaling; a no-op (backward-compatible) when the handler is absent.