@aiquants/directory-tree 3.7.0 → 3.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/dist/DirectoryTree.d.ts.map +1 -1
  2. package/dist/index.cjs +2 -2
  3. package/dist/index.js +364 -366
  4. package/dist/types.d.ts +1 -1
  5. package/dist/types.d.ts.map +1 -1
  6. package/package.json +3 -3
  7. package/src/DirectoryTree.tsx +18 -22
  8. package/src/types.ts +1 -1
  9. package/dist/src/DirectoryTree.d.ts +0 -24
  10. package/dist/src/DirectoryTree.d.ts.map +0 -1
  11. package/dist/src/DirectoryTreeGrid.d.ts +0 -64
  12. package/dist/src/DirectoryTreeGrid.d.ts.map +0 -1
  13. package/dist/src/TreeLine.d.ts +0 -9
  14. package/dist/src/TreeLine.d.ts.map +0 -1
  15. package/dist/src/cli.server.d.ts +0 -2
  16. package/dist/src/cli.server.d.ts.map +0 -1
  17. package/dist/src/entryRendering.d.ts +0 -50
  18. package/dist/src/entryRendering.d.ts.map +0 -1
  19. package/dist/src/gridUtils.d.ts +0 -47
  20. package/dist/src/gridUtils.d.ts.map +0 -1
  21. package/dist/src/index.d.ts +0 -14
  22. package/dist/src/index.d.ts.map +0 -1
  23. package/dist/src/logger.d.ts +0 -98
  24. package/dist/src/logger.d.ts.map +0 -1
  25. package/dist/src/scrollAnchor.d.ts +0 -39
  26. package/dist/src/scrollAnchor.d.ts.map +0 -1
  27. package/dist/src/types.d.ts +0 -591
  28. package/dist/src/types.d.ts.map +0 -1
  29. package/dist/src/useDirectoryTreeState.d.ts +0 -15
  30. package/dist/src/useDirectoryTreeState.d.ts.map +0 -1
  31. package/dist/src/useEntryInteraction.d.ts +0 -20
  32. package/dist/src/useEntryInteraction.d.ts.map +0 -1
  33. package/dist/tests/test-setup.d.ts +0 -1
  34. package/dist/tests/test-setup.d.ts.map +0 -1
  35. package/dist/vite.config.d.ts +0 -3
  36. package/dist/vite.config.d.ts.map +0 -1
  37. package/src/DirectoryTree.spec.md +0 -550
@@ -1,550 +0,0 @@
1
- # DirectoryTree Component Specification
2
-
3
- ## 1. Revision History
4
-
5
- | Version | Date | Author | Reviewer | Approver | Summary of Changes |
6
- | :--- | :--- | :--- | :--- | :--- | :--- |
7
- | 3.7.0 | 2026-08-08 | Claude Opus 5 | | | Implement the WAI-ARIA tree keyboard contract and complete the grid's ARIA structure — the two gaps 3.6.0 recorded as outstanding. Rows now use a **roving tabindex**: exactly one row is a tab stop, so tabbing past a 500-row tree costs one keystroke instead of 500. `ArrowUp`/`ArrowDown` move between visible rows, `Home`/`End` jump to either end, `ArrowRight` opens a collapsed directory or descends into an open one, `ArrowLeft` closes an open directory or returns to the parent, and `Space` activates a row alongside `Enter`. Because rows outside the render window do not exist in the DOM, navigation first calls `virtualScroll.scrollToIndex` and focuses the row when it registers, so movement works across the whole tree rather than only the rendered window. In grid mode the header, body and footer rows are now wrapped in `role="rowgroup"` elements — the body group is applied to the scroll-pane content element through the `contentProps` seam added in 3.5.0, which is where the `@aiquants/virtualscroll` contract says a composite role belongs. |
8
- | 3.6.1 | 2026-08-08 | Claude Opus 5 | | | Fix `aria-selected` to reflect `selection.selectedItems` in **every** mode. 3.6.0 read `selectedPath` in single mode, but `selectedPath` is the *currently-open* row highlight, a separate concept from the selection set that `selection.mode` governs — so a row the user had not selected was announced as selected. |
9
- | 3.6.0 | 2026-08-08 | Claude Opus 5 | | | Expose selection and identity to assistive tech. Rows emit `aria-selected` whenever `selection.mode` is not `"none"` (single mode reflects `selectedPath`, multiple reflects `selectedItems`), and the tree/treegrid emits `aria-multiselectable` in multiple mode — previously selection was conveyed only by background colour, so a non-sighted user could not tell what was selected or that multi-select was even available. New `visual.ariaLabel` / `visual.ariaLabelledBy` give the tree an accessible name; with several trees on a page it was previously unnameable through the public API. Grid mode additionally emits `aria-rowcount` on the container and `aria-rowindex` on each row, which a virtualized `treegrid` requires once only a window of rows is in the DOM. **Known remaining gap (pre-existing, not addressed here):** in grid mode the body rows sit below five roleless wrapper divs with no `rowgroup` / `presentation`, so the grid axis is still non-conforming; grid mode currently has no consumer in this repository. Row keyboard navigation (roving tabindex + arrow keys) is likewise still outstanding — every row remains a tab stop. |
10
- | 3.5.1 | 2026-08-08 | Claude Opus 5 | | | Hardening of the 3.5.0 `data` API after adversarial review. `null` / `undefined` values now omit the attribute entirely instead of rendering `data-x="undefined"` — the type forbids them, but a dynamic or JS-side value can still produce one, and a consumer testing attribute *presence* would read that as a real state. The key-conversion contract is also corrected: it lowercases and inserts a dash before a capital that follows a lowercase letter or digit, which is **not** identical to the DOM `dataset` reverse mapping (`aBC` becomes `a-bc`, not `a-b-c`) and is **not injective** (`panelCount` and `panel-count` collapse to the same attribute; within one object the later key wins). 3.5.0 documented these as equivalent, which was wrong. Tests added for the nullish case and for grid-mode `data-*` + position output. |
11
- | 3.5.0 | 2026-08-08 | Claude Opus 5 | | | Rows now declare their position in the tree: `aria-level` (1-based **logical** depth, so `visual.removeRootIndent` no longer misreports the hierarchy it only shifts visually), `aria-posinset` and `aria-setsize`, taken from the **post-sort** sibling order so the announced position always matches the rendered one. Grid rows gain `aria-posinset` / `aria-setsize` alongside the `aria-level` they already had. New `DirectoryEntry.data` renders extra `data-*` attributes on the row so consumers can expose state as attributes instead of CSS classes (class names are a styling contract and break silently under utility refactors); keys are given without the `data-` prefix and camelCase is converted to kebab-case exactly as the DOM `dataset` API does, since React otherwise drops the attribute with only a warning. The component's own `data-entry-*` attributes cannot be overridden. Also completes the pass-through audit started in 3.4.0: `virtualScroll.testId` and `virtualScroll.contentProps` were accepted by the type but never forwarded, and are now forwarded (they target the scroll pane, a different element from the `role="tree"` container this component owns, so there is no ARIA conflict). |
12
- | 3.4.0 | 2026-08-08 | Claude Opus 5 | | | Add the optional top-level `sort` prop (`DirectoryEntryComparator`), applied to every sibling group inside `collectTreeData` immediately before flattening. Only a shallow copy of each sibling array is sorted, so every `DirectoryEntry` object and every `children` array keeps its identity and consumer-side memoization (row memo, reference-preserving decorators, hydration caches) survives a re-sort; the caller's `entries` arrays are never mutated. `isLastChild` and the ancestor chain derive from the loop index, so connector geometry follows the sorted order automatically, in grid mode too. Ordering is deliberately a top-level prop rather than a `visual` member because it changes row semantics rather than presentation. Also fixes a latent defect exposed by any reordering: `virtualScroll.getItemKey` was accepted by the type but never destructured or forwarded, so `VirtualScroll` fell back to index keying and every row whose index-to-entry mapping changed was unmounted and remounted; it is now forwarded, defaulting to `entry.absolutePath`. |
13
- | 3.1.0 | 2026-07-31 | Claude Opus 5 | | | Add opt-in `virtualScroll.preserveScrollAnchor`: when the row list mutates (e.g. streaming insertions above the viewport), the first visible row is kept visually stationary via a pre-paint (`useLayoutEffect`) scroll correction. Pure helpers `captureScrollAnchor` / `resolveAnchorScroll` live in `scrollAnchor.ts` (unit-tested). The anchor is captured from the **live pane position** (`getScrollPosition()`, inset-adjusted) rather than the RAF-throttled `onScroll` mirror, so corrections landing mid-scroll do not rubber-band by the notification lag; the handle's clamped return value is adopted, and the component's own `scrollPosition` state is updated **in the same pre-paint flush** so the tree-line canvas / expand glyphs never misalign from the rows. No correction at the top of the list (scroll 0) and pixel-position fallback when the anchored row vanished. Known trade-off: the programmatic correction goes through the ScrollPane handle, which stops an in-progress pointer-drag inertia fling (same as the pre-existing compensation path). Also removed a leftover dead `isEmpty` local. |
14
- | 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. |
15
- | 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). |
16
- | 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. |
17
- | 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. |
18
- | 1.5 | 2025-11-10 | GitHub Copilot | | | Add showDirectoryIcons and showFileIcons props to control type icon visibility. |
19
- | 1.4 | 2025-11-10 | GitHub Copilot | | | Add showExpandIcons prop to toggle directory expand icon visibility. |
20
- | 1.3 | 2025-11-10 | GitHub Copilot | | | Add showTreeLines prop to allow toggling connector line rendering. |
21
- | 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. |
22
- | 1.1 | 2025-06-29 | GitHub Copilot | | | Add virtualization support using `useVirtualizer` hook. |
23
- | 1.0 | 2025-06-28 | Copilot | | | Newly created |
24
-
25
- ## 2. Introduction
26
-
27
- ### 2.1. Document Purpose
28
-
29
- This document provides the detailed design specifications for the `DirectoryTree` React component.
30
- 本書は `DirectoryTree` React コンポーネントの詳細設計仕様書です。
31
-
32
- ### 2.2. Background
33
-
34
- 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.
35
- ファイルやディレクトリ構造を扱うアプリケーションでは、階層データを効率的に表示する UI コンポーネントが必要です。以前の実装は、大規模なデータセットに対するパフォーマンスが低く、柔軟性のないスタイリングシステムでした。
36
-
37
- ### 2.3. Objective
38
-
39
- To provide a highly performant, customizable, and easy-to-use directory tree component. This component uses Tailwind CSS for flexible styling.
40
- パフォーマンスが高く、カスタマイズ可能で、使いやすいディレクトリツリーコンポーネントを提供することを目的とします。このコンポーネントは、Tailwind CSS を使用して柔軟なスタイリングを実現します。
41
-
42
- ### 2.4. Scope
43
-
44
- #### 2.4.1. In Scope
45
-
46
- * Displaying a hierarchical directory structure based on the `DirectoryEntry` type.
47
- `DirectoryEntry` 型に基づいた階層的なディレクトリ構造の表示。
48
- * Expanding and collapsing individual directories.
49
- 個々のディレクトリの展開と折りたたみ。
50
- * Recursively expanding and collapsing a directory and its children (e.g., via double-click).
51
- ディレクトリとその子要素の再帰的な展開と折りたたみ (例: ダブルクリック)。
52
- * File selection callback.
53
- ファイル選択時のコールバック機能。
54
- * Customizable styling via `className` and `style` props.
55
- `className` および `style` props を介したカスタマイズ可能なスタイリング。
56
- * Persisting the expansion state of each entity in `localStorage`.
57
- `localStorage` に各エンティティの展開状態を保存して維持する。
58
- * Explicitly handling `absolutePath` and `relativePath` within the `DirectoryTree`.
59
- `DirectoryTree` 内部で `absolutePath` と `relativePath` を明示的に扱う。
60
- * Improving user experience by using `startTransition` for state management of expansion.
61
- 展開状態の管理に `startTransition` を用いてUXを向上させる。
62
- * Rendering tree connector lines on a `<canvas>` overlay to visually represent the hierarchy and the open/closed state of directories.
63
- `<canvas>` オーバーレイにツリー接続線を描画し、ディレクトリの階層と開閉状態を視覚的に表現する。
64
- * Virtualization of directory items for improved performance with large directories (via `@aiquants/virtualscroll`).
65
- ディレクトリアイテムの仮想化により、大規模なディレクトリでのパフォーマンスを向上させる(`@aiquants/virtualscroll` を使用)。
66
- * 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.
67
- TreeGrid(列)モード: 凍結した名前/ツリー列と縦整列したデータ列、整列ヘッダ、任意の全 entries フッタ、数値領域の横スクロールを、任意の `grid` prop で提供する。
68
-
69
- #### 2.4.2. Out of Scope
70
-
71
- * File operations (create, delete, rename).
72
- ファイル操作 (作成、削除、名前変更)。
73
- * Drag-and-drop functionality.
74
- ドラッグアンドドロップ機能。
75
- * Context menu integration.
76
- コンテキストメニューの統合。
77
-
78
- #### 2.4.3. Future Expansion (Optional)
79
-
80
- * Integration with a file system API to dynamically load directory contents.
81
- ファイルシステム API と統合し、ディレクトリの内容を動的に読み込む機能。
82
- * Support for custom icons based on file type or directory state.
83
- ファイルタイプやディレクトリの状態に応じたカスタムアイコンのサポート。
84
-
85
- ### 2.5. Target Audience
86
-
87
- 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.
88
- 本書は `DirectoryTree` コンポーネントを使用または開発に貢献する開発者、およびその機能を理解する必要がある UI/UX デザイナーを対象としています。
89
-
90
- ### 2.6. References
91
-
92
- * `DirectoryEntry` type definition: [DirectoryTree.tsx](./DirectoryTree.tsx)
93
- * `useDirectoryTreeState` hook: [useDirectoryTreeState.ts](./useDirectoryTreeState.ts)
94
- * `TreeLine` component: [TreeLine.tsx](./TreeLine.tsx)
95
-
96
- ### 2.7. Prerequisites and Constraints
97
-
98
- * The component must be used within a React application.
99
- コンポーネントは React アプリケーション内で使用する必要があります。
100
- * Styling is managed via Tailwind CSS and `tailwind-variants`. Proper configuration of Tailwind CSS is required.
101
- スタイリングは Tailwind CSS と `tailwind-variants` を介して管理されます。Tailwind CSS の適切な設定が必要です。
102
- * Input data must conform to the `DirectoryEntry[]` type structure.
103
- 入力データは `DirectoryEntry[]` 型の構造に準拠する必要があります。
104
-
105
- ### 2.8. Architectural Policy and Technology Selection
106
-
107
- * **State Management**: The expansion state of the tree is managed by the `useDirectoryTreeState` hook, separating state logic from the presentation component.
108
- **状態管理**: ツリーの展開状態は `useDirectoryTreeState` フックによって管理され、状態ロジックをプレゼンテーションコンポーネントから分離します。
109
- * **Styling**: `tailwind-variants` is used for creating a flexible and customizable styling system based on component state and props.
110
- **スタイリング**: `tailwind-variants` を使用して、コンポーネントの状態と Props に基づいた柔軟でカスタマイズ可能なスタイリングシステムを構築します。
111
- * **Componentization**: The component is broken down into smaller, manageable parts like `DirectoryEntryItem` and `TreeLine` to improve maintainability and reusability.
112
- **コンポーネント化**: コンポーネントは `DirectoryEntryItem` や `TreeLine` のような小さく管理しやすいパーツに分割され、保守性と再利用性を向上させています。
113
-
114
- ## 3. Component API
115
-
116
- ### 3.1. Data Structures
117
-
118
- #### 3.1.1. `DirectoryEntry`
119
-
120
- The fundamental data structure for representing a file or directory.
121
- ファイルまたはディレクトリを表す基本的なデータ構造。
122
-
123
- | Property | Type | Description |
124
- | :--- | :--- | :--- |
125
- | `name` | `string` | The name of the file or directory. ファイルまたはディレクトリの名前。 |
126
- | `absolutePath` | `string` | The absolute path of the entry. エントリの絶対パス。 |
127
- | `relativePath` | `string` | The path of the entry relative to the root. ルートからの相対パス。 |
128
- | `children` | `DirectoryEntry[] \| null` | An array of child entries if it's a directory, otherwise `null`. ディレクトリの場合は子エントリの配列、それ以外の場合は `null`。 |
129
- | `data` | `Record<string, string \| number \| boolean>` | Extra `data-*` attributes rendered on this entry's row. Keys omit the `data-` prefix; a dash is inserted before each capital following a lowercase letter or digit and the whole key is lowercased (`{ panelCount: 2 }` → `data-panel-count="2"`). This is **not** the DOM `dataset` reverse mapping (`aBC` → `a-bc`) and is **not injective** (`panelCount` and `panel-count` collide; the later key wins). Values are stringified; `null` / `undefined` omit the attribute. The component's own `data-entry-*` attributes always win. この行へ付与する追加の `data-*` 属性。キーは `data-` を含めず、camelCase は `dataset` と同じ規約で kebab-case になる。自前の `data-entry-*` は上書き不可。 |
130
-
131
- **Why `data` exists**: it lets a consumer expose row state as an *attribute* rather than as a CSS class, so
132
- styling and test locators never depend on class names — those are a styling contract that changes freely under
133
- utility refactors, prefix migrations and class sorting, and break silently when they do.
134
- `data` は行の状態を CSS クラスではなく属性として公開するための口。クラス名はスタイリング契約であり、
135
- 整形や prefix 変更で無言に壊れるため、スタイルやテストの依存先にしない。
136
-
137
- ### 3.2. Props
138
-
139
- The `DirectoryTree` component accepts the following props:
140
- `DirectoryTree` コンポーネントは、以下の props を受け入れます。
141
-
142
- | Prop Name | Type | Required | Default | Description |
143
- | :--- | :--- | :--- | :--- | :--- |
144
- | `entries` | `DirectoryEntry[]` | Yes | - | The array of root directory entries to display. 表示するルートディレクトリのエントリの配列。 |
145
- | `expansion` | `object` | Yes | - | Configuration for tree expansion state and behavior. ツリーの展開状態と動作の設定。 |
146
- | `selection` | `object` | Yes | - | Configuration for item selection. アイテム選択の設定。 |
147
- | `visual` | `object` | No | - | Visual customization options. 表示のカスタマイズオプション。 |
148
- | `visual.ariaLabel` / `visual.ariaLabelledBy` | `string` | No | - | Accessible name for the tree as a whole. `ariaLabelledBy` (id of a visible naming element) takes precedence. ツリー全体のアクセシブル名。`ariaLabelledBy` が優先。 |
149
- | `virtualScroll` | `DirectoryTreeVirtualScrollOptions` | No | - | Additional options for VirtualScroll integration. Includes `viewportHeightOverride` and `preserveScrollAnchor` (opt-in, default `false`: keeps the first visible row visually stationary across row-list mutations such as streaming insertions above the viewport; inactive at scroll 0; falls back to pixel-position when the anchored row vanished). VirtualScroll の設定を上書きするオプション。`preserveScrollAnchor` (既定 `false`) を有効化すると、行リスト変異時に先頭可視行を画面上で静止させる (最上部では不作動、アンカー行消失時はピクセル位置維持へフォールバック)。 |
150
- | `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)。 |
151
- | `sort` | `DirectoryEntryComparator` | No | - | Comparator applied to every sibling group before flattening. Only a shallow copy of each sibling array is sorted, so entry objects and their `children` arrays keep identity. Omit to render in the given order. **Stable reference required.** See §3.2.5. フラット化前に各兄弟グループへ適用する比較関数。兄弟配列の浅いコピーのみを並べ替えるため、エントリと `children` の identity は保持される。省略時は与えられた順序のまま。**参照安定必須**(§3.2.5)。 |
152
-
153
- #### 3.2.1. `expansion` Configuration
154
-
155
- | Property | Type | Required | Default | Description |
156
- | :--- | :--- | :--- | :--- | :--- |
157
- | `toggle` | `(path: string) => void` | Yes | - | Function to toggle directory expansion state. ディレクトリの展開状態を切り替える関数。 |
158
- | `isExpanded` | `(path: string) => boolean` | Yes | - | Function to check if a directory is expanded. ディレクトリが展開されているかを確認する関数。 |
159
- | `expandMultiple` | `(paths: string[]) => void` | Yes | - | Function to expand multiple directories. 複数のディレクトリを展開する関数。 |
160
- | `collapseMultiple` | `(paths: string[]) => void` | Yes | - | Function to collapse multiple directories. 複数のディレクトリを折りたたむ関数。 |
161
- | `isPending` | `boolean` | No | `false` | Whether the tree is in a pending state. ツリーが保留状態かどうか。 |
162
- | `alwaysExpanded` | `boolean` | No | `false` | If true, all directories are always expanded. true の場合、すべてのディレクトリが常に展開されます。 |
163
- | `doubleClickAction` | `'recursive' \| 'toggle'` | No | `'recursive'` | Action on double-clicking a directory. ディレクトリをダブルクリックしたときのアクション。 |
164
-
165
- #### 3.2.2. `selection` Configuration
166
-
167
- | Property | Type | Required | Default | Description |
168
- | :--- | :--- | :--- | :--- | :--- |
169
- | `onEntryClick` | `(event: DirectoryTreeClickEvent) => void` | Yes | - | Callback triggered when an entry is clicked. エントリがクリックされたときのコールバック。 |
170
- | `selectedPath` | `string \| null` | No | - | The currently selected path. 現在選択されているパス。 |
171
- | `mode` | `'none' \| 'single' \| 'multiple'` | No | `'none'` | Selection mode for items. アイテムの選択モード。 |
172
- | `selectedItems` | `Set<string>` | No | - | Set of paths for currently selected items. 現在選択されているアイテムのパスのセット。 |
173
- | `onSelectionChange` | `(entry: DirectoryEntry, isSelected: boolean) => void` | No | - | Callback when item selection changes. アイテム選択状態変更時のコールバック。 |
174
-
175
- #### 3.2.3. `visual` Configuration
176
-
177
- | Property | Type | Required | Default | Description |
178
- | :--- | :--- | :--- | :--- | :--- |
179
- | `className` | `string` | No | - | Additional CSS classes to apply to the root container. コンテナ用のオプション CSS クラス名。 |
180
- | `style` | `React.CSSProperties` | No | - | Inline styles to apply to the root container. コンテナ用のオプションのインラインスタイル。 |
181
- | `lineColor` | `string` | No | `'#A0AEC0'` | The color of the tree lines. ツリーラインの色。 |
182
- | `showTreeLines` | `boolean` | No | `true` | Whether to render connector tree lines. ツリーのコネクタラインを描画するかどうか。 |
183
- | `showExpandIcons` | `boolean` | No | `true` | Whether to render directory expand icons. ディレクトリの展開アイコンを描画するかどうか。 |
184
- | `showDirectoryIcons` | `boolean` | No | `true` | Whether to render directory type icons. ディレクトリアイコンを描画するかどうか。 |
185
- | `showFileIcons` | `boolean` | No | `true` | Whether to render file type icons. ファイルアイコンを描画するかどうか。 |
186
- | `iconOverrides` | `DirectoryTreeIconOverrides` | No | - | Icon overrides applied globally. グローバルに適用するアイコン差し替え設定。 |
187
- | `expandIconSize` | `number` | No | - | Size of the expand icon. 展開アイコンのサイズ。 |
188
- | `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 を安定させること。 |
189
- | `removeRootIndent` | `boolean` | No | `false` | If true, removes indentation for root-level items. ルートレベルのアイテムのインデントを削除するかどうか。 |
190
- | `highlightStyles` | `HighlightStyles` | No | - | Custom hover and selection styles. ホバー時および選択時のカスタムスタイル。 |
191
- | `entryClassName` | `string` | No | - | Additional CSS classes for each entry row. 各エントリ(行)に適用する追加の CSS クラス名。 |
192
- | `entryStyle` | `React.CSSProperties` | No | - | Additional inline styles for each entry row. 各エントリ(行)に適用する追加のインラインスタイル。 |
193
- | `nameClassName` | `string` | No | - | Additional CSS classes for the name label. 名前(ラベル)部分に適用する追加の CSS クラス名。 |
194
- | `nameStyle` | `React.CSSProperties` | No | - | Additional inline styles for the name label. 名前(ラベル)部分に適用する追加のインラインスタイル。 |
195
- | `directoryNameClassName` | `string` | No | - | Additional CSS classes specifically for directory names. ディレクトリ名特有の追加の CSS クラス名。 |
196
- | `directoryNameStyle` | `React.CSSProperties` | No | - | Additional inline styles specifically for directory names. ディレクトリ名特有の追加のインラインスタイル。 |
197
- | `fileNameClassName` | `string` | No | - | Additional CSS classes specifically for file names. ファイル名特有の追加の CSS クラス名。 |
198
- | `fileNameStyle` | `React.CSSProperties` | No | - | Additional inline styles specifically for file names. ファイル名特有の追加のインラインスタイル。 |
199
-
200
- #### 3.2.4. `grid` Configuration (TreeGrid columns mode)
201
-
202
- When `grid` is provided, the tree renders as a **TreeGrid**: the name/tree column is frozen on the left
203
- (indentation and connector lines stay confined there) while the remaining columns render as a
204
- vertically-aligned grid — with an aligned column header, an optional footer aggregating over **all**
205
- entries, and a horizontally scrollable numeric region. When omitted, the classic label tree is rendered.
206
- `grid` 指定時は TreeGrid として描画する(凍結名前列+整列データ列+整列ヘッダ/フッタ+数値領域横スクロール)。省略時は従来のラベルツリー。
207
-
208
- `DirectoryTreeGrid`:
209
-
210
- | Property | Type | Required | Default | Description |
211
- | :--- | :--- | :--- | :--- | :--- |
212
- | `columns` | `DirectoryTreeColumn[]` | Yes | - | Column definitions (**stable reference required**). `columns[0]` is always the name/tree column. 列定義(参照安定必須)。`columns[0]` が名前/ツリー列。 |
213
- | `showHeader` | `boolean` | No | `true` | Render the aligned column header row. 整列した列ヘッダ行を描画するか。 |
214
- | `showFooter` | `boolean` | No | `false` | Render the footer row (aggregates over all entries). フッタ行(全 entries 集計)を描画するか。 |
215
- | `headerClassName` | `string` | No | - | Extra class for the header row. ヘッダ行の追加クラス。 |
216
- | `footerClassName` | `string` | No | - | Extra class for the footer row. フッタ行の追加クラス。 |
217
- | `rowClassName` | `string \| ((entry) => string)` | No | - | Extra class (or per-entry factory) for body rows. 行の追加クラス(またはエントリ別ファクトリ)。 |
218
- | `scrollBarWidth` | `number` | No | `virtualScroll.scrollBarOptions.width ?? 12` | Vertical scrollbar width used to align the header/footer numeric viewport with the body. 縦バー幅(ヘッダ/フッタと本体の数値ビューポート整合に使用)。 |
219
-
220
- `DirectoryTreeColumn`:
221
-
222
- | Property | Type | Required | Default | Description |
223
- | :--- | :--- | :--- | :--- | :--- |
224
- | `key` | `string` | Yes | - | Unique column key. 一意なキー。 |
225
- | `header` | `ReactNode` | No | - | Column header content. 列ヘッダ内容。 |
226
- | `footer` | `ReactNode \| ((allEntries: DirectoryEntry[]) => ReactNode)` | No | - | Footer content. The function form receives **every node of `entries` (collapsed subtrees included)**. フッタ内容。関数形は entries の全ノード(折り畳み含む)を受け取る。 |
227
- | `width` | `number` | No | `240` (name) / `96` (data) | Column width in px (name column = frozen width; data column = grid track). 列幅 (px)。 |
228
- | `align` | `'left' \| 'right' \| 'center'` | No | `'left'` | Cell alignment. セル寄せ。 |
229
- | `className` | `string` | No | - | Extra class for this column's cells. この列のセルの追加クラス。 |
230
- | `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 はライブラリが描画。 |
231
-
232
- **Rendering rules / behavior:**
233
-
234
- 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.
235
- 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).
236
- 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.
237
- 4. Grid mode uses `role="treegrid"` / `row` / `gridcell` / `columnheader`; `aria-expanded` / `aria-level` are set on the row.
238
- 5. `grid.columns` and each `render` / `footer` **must be stable references** (memoize them) — otherwise every visible row re-renders.
239
- 6. `visual.removeRootIndent` is **ignored in grid mode** (the frozen name column must start at `x=0`).
240
- 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.
241
- 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).
242
-
243
- #### 3.2.5. `sort` (sibling ordering)
244
-
245
- `sort` is a plain comparator over two entries that share the same parent. It is applied inside the single
246
- traversal that turns sibling order into row order, immediately before flattening, at **every** depth.
247
- `sort` は同一の親を持つ 2 エントリを比較する関数で、兄弟順序が行順序へ変換される唯一の走査内で、フラット化直前に全階層へ適用される。
248
-
249
- ```typescript
250
- export type DirectoryEntryComparator = (a: DirectoryEntry, b: DirectoryEntry) => number
251
- ```
252
-
253
- **Guarantees / behavior:**
254
-
255
- 1. **Entry identity is preserved.** Only a shallow copy of each sibling array is sorted (`[...siblings].sort(sort)`);
256
- no `DirectoryEntry` object and no `children` array is cloned or mutated. Consumer-side memoization that keys on
257
- entry identity — the internal row memo, reference-preserving decorators, hydration caches — therefore keeps working.
258
- エントリ本体と `children` 配列は複製も変更もされないため、identity に依存する利用側のメモ化はそのまま機能する。
259
- 2. **The `entries` prop is never mutated.** The caller's arrays are left in their original order.
260
- 3. **Connector geometry follows the sorted order.** `isLastChild` and the ancestor chain derive from the loop index,
261
- so the last *rendered* sibling receives the stub connector.
262
- 4. Ordering is not a presentation concern (it changes row semantics and connector geometry, and applies identically in
263
- grid mode), which is why `sort` is a top-level prop rather than a member of `visual`.
264
- 5. **Stable reference required** (memoize with `useMemo` / `useCallback`) — a new identity each render re-runs the
265
- whole traversal, the same constraint as `visual.itemHeight` and `grid.columns`.
266
- 6. Omitting `sort` skips the copy entirely: entries render in exactly the order given.
267
- 7. Sorting is applied to **rows only**. `grid.columns[].footer` still receives every node of the `entries` prop in the
268
- **prop's** order, not the rendered order. Most footers aggregate (sum / count) and are unaffected, but a footer whose
269
- output depends on order (e.g. "first item", a running sequence) must apply the same comparator itself.
270
- フッタは描画順ではなく `entries` の順序で全ノードを受け取る。順序に依存するフッタは同じ比較関数を自前で適用すること。
271
-
272
- **Row keying.** `virtualScroll.getItemKey` is forwarded to `VirtualScroll`, and when it is omitted rows are keyed by
273
- `entry.absolutePath` instead of by index. This is what lets a re-sort *move* existing rows rather than unmount and
274
- remount every row whose index-to-entry mapping changed.
275
- `virtualScroll.getItemKey` は `VirtualScroll` へ転送され、未指定時の既定行キーは `entry.absolutePath`。これにより並べ替え時に既存行は移動するだけで再生成されない。
276
-
277
- ```typescript
278
- const compare = useMemo<DirectoryEntryComparator>(() => (a, b) => a.name.localeCompare(b.name, "en", { numeric: true }), [])
279
-
280
- <DirectoryTree entries={entries} expansion={...} selection={...} sort={compare} />
281
- ```
282
-
283
- ### 3.3. Usage
284
-
285
- Here is a basic example of how to use the `DirectoryTree` component with the `useDirectoryTreeState` hook.
286
- これは `DirectoryTree` コンポーネントを `useDirectoryTreeState` フックと共に使用する基本的な使用例です。
287
-
288
- **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.
289
- **注:** このコンポーネントは、展開状態を管理するために `useDirectoryTreeState` フックと共に使用するように設計されています。`lineColor` は現在のテーマに基づいて制御できます。
290
-
291
- ```tsx
292
- import React, { useState } from 'react'
293
- import { DirectoryTree, DirectoryEntry } from './DirectoryTree' // Adjust the import path
294
- import { useDirectoryTreeState } from './useDirectoryTreeState' // Adjust the import path
295
- import { useTheme } from './useTheme' // Adjust the import path
296
-
297
- const sampleEntries: DirectoryEntry[] = [
298
- {
299
- name: 'src',
300
- absolutePath: '/src',
301
- relativePath: 'src',
302
- children: [
303
- {
304
- name: 'components',
305
- absolutePath: '/src/components',
306
- relativePath: 'src/components',
307
- children: [
308
- {
309
- name: 'Button.tsx',
310
- absolutePath: '/src/components/Button.tsx',
311
- relativePath: 'src/components/Button.tsx',
312
- children: null,
313
- },
314
- ],
315
- },
316
- {
317
- name: 'App.tsx',
318
- absolutePath: '/src/App.tsx',
319
- relativePath: 'src/App.tsx',
320
- children: null,
321
- },
322
- ],
323
- },
324
- {
325
- name: 'package.json',
326
- absolutePath: '/package.json',
327
- relativePath: 'package.json',
328
- children: null,
329
- },
330
- ]
331
-
332
- const App = () => {
333
- const [selectedFile, setSelectedFile] = useState<string | null>(null)
334
- const { theme } = useTheme()
335
- const treeState = useDirectoryTreeState({
336
- storageKey: 'my-tree-state',
337
- })
338
-
339
- // Calculate line color based on theme
340
- const lineColor = theme === "dark" ? "#4A5568" : "#A0AEC0"
341
-
342
- const handleEntryClick = (event: DirectoryTreeClickEvent) => {
343
- console.log(`Entry clicked: ${event.entry.absolutePath}`)
344
- setSelectedFile(event.entry.absolutePath)
345
- }
346
-
347
- return (
348
- <div style={{ width: '300px', height: '500px', border: '1px solid #ccc' }}>
349
- <DirectoryTree
350
- entries={sampleEntries}
351
- onEntryClick={handleEntryClick}
352
- selectedPath={selectedFile}
353
- toggle={treeState.toggle}
354
- isExpanded={treeState.isExpanded}
355
- expandMultiple={treeState.expandMultiple}
356
- collapseMultiple={treeState.collapseMultiple}
357
- isPending={treeState.isPending}
358
- lineColor={lineColor}
359
- />
360
- {selectedFile && <p>Selected file: {selectedFile}</p>}
361
- </div>
362
- )
363
- }
364
- />
365
- {selectedFile && <p>Selected file: {selectedFile}</p>}
366
- </div>
367
- )
368
- }
369
-
370
- export default App
371
- ```
372
-
373
- ## 4. Internal Hooks
374
-
375
- This section describes the hooks used internally by the `DirectoryTree` component.
376
- このセクションでは、`DirectoryTree` コンポーネントが内部で使用するフックについて説明します。
377
-
378
- ### 4.1. `useDirectoryTreeState`
379
-
380
- #### 4.1.1. Overview
381
-
382
- 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.
383
- このフックは、ディレクトリツリーの展開状態を管理します。状態を `localStorage` に永続化してセッション間で維持し、`useTransition` を使用して UI をブロックせずに状態更新を実行します。
384
-
385
- #### 4.1.2. Input (Options)
386
-
387
- | Prop Name | Type | Required | Default | Description |
388
- | :--- | :--- | :--- | :--- | :--- |
389
- | `initialEntries` | `DirectoryEntry[]` | No | `[]` | The initial set of directory entries. Used to determine the default expansion state if no state is found in `localStorage`. 初期ディレクトリ エントリのセット。`localStorage` に状態が見つからない場合に、デフォルトの展開状態を決定するために使用されます。 |
390
- | `storageKey` | `string` | No | `directory-tree-state` | The key used to store the expansion state in `localStorage`. 展開状態を `localStorage` に保存するために使用されるキー。 |
391
-
392
- #### 4.1.3. Output
393
-
394
- The hook returns a `DirectoryTreeState` object with the following properties:
395
- このフックは、次のプロパティを持つ `DirectoryTreeState` オブジェクトを返します。
396
-
397
- | Property | Type | Description |
398
- | :--- | :--- | :--- |
399
- | `expanded` | `Set<string>` | A set of absolute paths of the expanded directories. 展開されているディレクトリの絶対パスのセット。 |
400
- | `toggle` | `(path: string) => void` | Function to toggle the expansion state of a directory. ディレクトリの展開状態を切り替える関数。 |
401
- | `expand` | `(path: string) => void` | Function to expand a directory. ディレクトリを展開する関数。 |
402
- | `collapse` | `(path: string) => void` | Function to collapse a directory. ディレクトリを折りたたむ関数。 |
403
- | `collapseMultiple` | `(paths: string[]) => void` | Function to collapse multiple directories. 複数のディレクトリを折りたたむ関数。 |
404
- | `expandMultiple` | `(paths: string[]) => void` | Function to expand multiple directories. 複数のディレクトリを展開する関数。 |
405
- | `isPending` | `boolean` | A flag that is true when a state transition is pending. 状態遷移が保留中の場合に true となるフラグ。 |
406
-
407
- ## 5. Data Structures
408
-
409
- ### 5.1. `DirectoryEntry`
410
-
411
- This type represents a single node in the directory tree.
412
- この型は、ディレクトリツリー内の単一ノードを表します。
413
-
414
- | Property | Type | Description |
415
- | :--- | :--- | :--- |
416
- | `name` | `string` | The name of the file or directory. ファイルまたはディレクトリの名前。 |
417
- | `type` | `"file" \| "directory"` | The type of the entry. エントリの種別。 |
418
- | `absolutePath` | `string` | The absolute path of the entry. エントリの絶対パス。 |
419
- | `relativePath` | `string` | The relative path of the entry. エントリの相対パス。 |
420
- | `children` | `DirectoryEntry[] \| undefined` | An array of child entries if the type is `directory`. `type` が `directory` の場合の子エントリの配列。 |
421
-
422
- ### 5.2. `DirectoryTreeState`
423
-
424
- This type represents the state object managed by the `useDirectoryTreeState` hook.
425
- この型は `useDirectoryTreeState` フックによって管理される状態オブジェクトを表します。
426
-
427
- | Property | Type | Description |
428
- | :--- | :--- | :--- |
429
- | `expanded` | `Set<string>` | A set of absolute paths of the expanded directories. 展開されているディレクトリの絶対パスのセット。 |
430
- | `toggle` | `(path: string) => void` | Function to toggle the expansion state of a directory. ディレクトリの展開状態を切り替える関数。 |
431
- | `expand` | `(path: string) => void` | Function to expand a directory. ディレクトリを展開する関数。 |
432
- | `collapse` | `(path: string) => void` | Function to collapse a directory. ディレクトリを折りたたむ関数。 |
433
- | `collapseMultiple` | `(paths: string[]) => void` | Function to collapse multiple directories. 複数のディレクトリを折りたたむ関数。 |
434
- | `expandMultiple` | `(paths: string[]) => void` | Function to expand multiple directories. 複数のディレクトリを展開する関数。 |
435
- | `isPending` | `boolean` | A flag that is true when a state transition is pending. 状態遷移が保留中の場合に true となるフラグ。 |
436
-
437
- ## 6. Functional Requirements
438
-
439
- ### 6.1. Directory Expansion and Collapse
440
-
441
- * **Single Click**: A single click on a directory icon or name toggles its expansion state (expanded or collapsed).
442
- * **Double Click**: A double click on a directory can trigger one of two behaviors, selectable via a prop:
443
- 1. Toggle the expansion state of all descendant directories.
444
- 2. Recursively expand or collapse the directory and all its subdirectories.
445
- * **シングルクリック**: ディレクトリのアイコンまたは名前をシングルクリックすると、その展開状態 (展開または折りたたみ) が切り替わります。
446
- * **ダブルクリック**: ディレクトリをダブルクリックすると、プロパティを介して選択可能な 2 つの動作のいずれかがトリガーされます。
447
- 1. すべての子孫ディレクトリの展開状態を切り替える。
448
- 2. ディレクトリとそのすべてのサブディレクトリを再帰的に展開または折りたたむ。
449
-
450
- ### 6.2. File Selection
451
-
452
- * A single click on a file name triggers the `onEntryClick` callback, passing a `DirectoryTreeClickEvent` containing the entry and metadata.
453
- * The selected file is highlighted.
454
- * ファイル名をクリックすると `onEntryClick` コールバックがトリガーされ、エントリとメタデータを含む `DirectoryTreeClickEvent` が渡されます。
455
- * 選択されたファイルがハイライト表示されます。
456
-
457
- ## 7. Non-Functional Requirements
458
-
459
- ### 7.1. Performance
460
-
461
- * The component must render efficiently, even with a large number of files and directories.
462
- * `React.memo` should be used for `DirectoryEntryItem` to prevent unnecessary re-renders.
463
- * The `useDirectoryTreeState` hook will use `useTransition` to prevent UI blocking during state updates, improving the user experience.
464
- * 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.
465
- * 多数のファイルやディレクトリがあっても、コンポーネントは効率的にレンダリングされる必要があります。
466
- * 不要な再レンダリングを防ぐために、`DirectoryEntryItem` には `React.memo` を使用する必要があります。
467
- * grid モードでは `VirtualScroll` 要素をメモ化し、横スクロール(`--dt-hscroll` 変数のみ変化)で仮想化本体を再レンダーしない。`DirectoryEntryItem` / `DirectoryTreeGridRow` はいずれも `React.memo` 対象。
468
- * `useDirectoryTreeState` フックは `useTransition` を使用して、状態更新中の UI ブロッキングを防ぎ、ユーザーエクスペリエンスを向上させます。
469
-
470
- ### 7.2. Styling
471
-
472
- * The component is styled using Tailwind CSS for flexibility.
473
- * The color and width of the tree lines are customizable via props.
474
- * コンポーネントは、柔軟性のために Tailwind CSS を使用してスタイリングされます。
475
- * ツリーラインの色と幅は、プロパティを介してカスタマイズ可能です。
476
-
477
- ## 8. Dependencies
478
-
479
- * `react` / `react-dom` (peer dependencies)
480
- * `@aiquants/virtualscroll` (virtual scrolling engine; also provides the horizontal `ScrollBar` and `onWheelHorizontal`)
481
- * `@heroicons/react`, `@phosphor-icons/react` (default type / expand icons)
482
- * `tailwind-merge` (class-name merging)
483
- * Tailwind CSS v4 (styling)
484
-
485
- ## 9. Test Specification
486
-
487
- The package ships a comprehensive Vitest suite. Coverage is **100% (statements / functions / lines)** on the
488
- new TreeGrid modules (`gridUtils.ts`, `useEntryInteraction.ts`, `entryRendering.tsx`, `DirectoryTreeGrid.tsx`)
489
- and 100% statements/functions/lines on `DirectoryTree.tsx` (residual branches are defensive null-safety/dedup
490
- guards). Run `pnpm run test:coverage`.
491
-
492
- ### 9.1. Classic tree ([DirectoryTree.test.tsx](../tests/DirectoryTree.test.tsx))
493
-
494
- * **Basic Rendering**: the file/directory hierarchy renders (file name, expanding directories, etc.).
495
- * **Selection Action**: clicking a file triggers the selection callbacks (`onEntryClick`) with correct parameters.
496
- * **Custom Styling**: highlight class names (`directorySelectedClassName` / `itemSelectedClassName`) and styles are applied to active entries.
497
- * **Hover Interaction**: custom hover styling (`hoverClassName` / `hoverStyle`) is applied on mouse enter.
498
- * **Entry-specific Custom Styling**: entry (`entryClassName`/`entryStyle`) and name (`nameClassName`/`nameStyle`, `directoryNameClassName`/`directoryNameStyle`, `fileNameClassName`/`fileNameStyle`) classes/styles are merged and applied.
499
-
500
- ### 9.2. Behavior ([DirectoryTree.behavior.test.tsx](../tests/DirectoryTree.behavior.test.tsx))
501
-
502
- * **Interaction**: plain-row `onMouseLeave` / `onKeyDown(Enter)`; double-click actions (`expandMultiple` on all-collapsed, `collapseMultiple` on all-expanded, `collapseMultiple` on mixed+toggle).
503
- * **removeRootIndent / empty entries**: root indent removal renders without error; empty `entries` renders the placeholder container only.
504
- * **Tree-line geometry render**: an expanded tree with `viewportHeightOverride` + `showTreeLines` paints the connector canvas.
505
- * **Scroll callbacks**: vertical wheel drives `handleVirtualScroll` / `handleRangeChange`.
506
- * **Plain-row style branches**: selected file / itemSelected / directory selection (default & override); icon-hidden; `initialScrollOffset`; entry-reference-change re-render.
507
- * **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).
508
-
509
- ### 9.3. TreeGrid mode ([DirectoryTreeGrid.test.tsx](../tests/DirectoryTreeGrid.test.tsx))
510
-
511
- * **Semantics**: `role="treegrid"` when `grid` is set, `role="tree"` otherwise; aligned column headers.
512
- * **Alignment invariant**: name cells indent by depth (`0/16/32px`); data cells carry **no** per-depth padding.
513
- * **ClassName consistency**: verifies that `columns[i].className` is applied to body, header, and footer cells for both the name column and numeric columns.
514
- * **Footer**: `showFooter` aggregates over all entries (collapsed subtrees included); function and `ReactNode` footer forms.
515
- * **Row states**: selection (`selectedPath` / `selectedItems`), highlight classes/styles, hover, `align=center`, `rowClassName` factory, custom / fallback name render, name-only columns, empty data cell.
516
- * **removeRootIndent ignored in grid** (normal `0/16px` indent preserved); **empty grid** still renders header/footer/`treegrid` role.
517
- * **Memo comparator** (`isEntryExpanded`, entry-reference change, directory expansion change).
518
- * **`isEntryExpanded`** helper: directory expanded/collapsed, file short-circuit.
519
-
520
- ### 9.4. Sibling ordering & row keying ([DirectoryTree.sort.test.tsx](../tests/DirectoryTree.sort.test.tsx))
521
-
522
- * **Default order**: without `sort`, rows appear in exactly the input order.
523
- * **Ordering**: the comparator orders root siblings and, with the same comparator, the siblings of every expanded subtree; a descending comparator produces the exact inverse of the ascending one.
524
- * **Identity preservation**: after sorting, the entry object handed to a row is `Object.is`-identical to the one in the input tree, and so is its `children` array.
525
- * **Non-mutation**: the caller's `entries` arrays keep their original order.
526
- * **Row stability**: re-rendering with a different comparator *moves* the DOM node of an unchanged entry rather than recreating it.
527
- * **`getItemKey` forwarding**: a caller-supplied `virtualScroll.getItemKey` is actually invoked, and the default keys rows by `absolutePath` (proven by reordering `entries` and asserting DOM-node identity).
528
-
529
- ### 9.5. Row position semantics, `data-*` and pass-through ([DirectoryTree.a11y-and-passthrough.test.tsx](../tests/DirectoryTree.a11y-and-passthrough.test.tsx))
530
-
531
- * **`aria-level`**: 1-based logical depth for roots and nested rows, and **unchanged by `visual.removeRootIndent`** (which shifts only the visual indent).
532
- * **`aria-posinset` / `aria-setsize`**: position and sibling count per group, independent between a parent's group and its children's.
533
- * **Post-sort position**: with a comparator applied, the announced position matches the rendered order at every depth — the announcement can never contradict what is drawn.
534
- * **`entry.data`**: rendered as `data-*`; camelCase converted to kebab-case; absent/empty `data` adds no attributes; the component's own `data-entry-*` cannot be overridden.
535
- * **Pass-through**: `virtualScroll.testId` and `virtualScroll.contentProps` actually reach `VirtualScroll` (regression gate for the typed-but-dropped class of defect).
536
-
537
- * **Keyboard contract** ([DirectoryTree.keyboard.test.tsx](../tests/DirectoryTree.keyboard.test.tsx)): exactly one tab stop at all times and it follows the active row; Arrow/Home/End movement including the no-op at both ends; `ArrowRight` opening a collapsed directory vs. descending into an open one; `ArrowLeft` closing vs. returning to the parent; `Enter` and `Space` both activating.
538
- * **Selection semantics**: `aria-selected` is absent when `selection.mode` is `"none"` and otherwise reflects `selectedItems` in every mode (never `selectedPath`, which is the open-row highlight rather than a selection); `aria-multiselectable` appears only in multiple mode.
539
- * **Accessible name**: `visual.ariaLabel` names the tree; `visual.ariaLabelledBy` takes precedence and suppresses `aria-label`.
540
-
541
- ### 9.6. Pure helpers
542
-
543
- * **[gridUtils.test.ts](../tests/gridUtils.test.ts)**: `buildNumericTemplate`, `computeGridMetrics`, `clampHScroll`, `flattenAllEntries` (incl. default/invalid widths, zero-width viewport, NaN clamp).
544
- * **[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.
545
- * **[useEntryInteraction.test.tsx](../tests/useEntryInteraction.test.tsx)**: file select, directory single-click (delayed toggle), double-click (recursive), `preventDefault`, unmount timer cleanup.
546
- * **[entryRendering.test.tsx](../tests/entryRendering.test.tsx)**: `resolveExpandIcon`, `resolveEntryIcon` (all icon paths + sanitizer edge cases), `getFileExtension`.
547
-
548
- ### 9.7. VirtualScroll horizontal wheel (`@aiquants/virtualscroll`)
549
-
550
- * **[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.