@aiquants/directory-tree 3.0.4 → 3.1.0

package/src/DirectoryTree.tsx

@@ -0,0 +1,978 @@
+/**
+ * @module DirectoryTree
+ * @description A component to display a directory tree structure.
+ *              ディレクトリツリー構造を表示するためのコンポーネント。
+ */
+import { ScrollBar, VirtualScroll, type VirtualScrollHandle, type VirtualScrollRange } from "@aiquants/virtualscroll"
+import type { CSSProperties, MouseEvent } from "react"
+import { Fragment, memo, useCallback, useEffect, useMemo, useRef, useState } from "react"
+import { twMerge } from "tailwind-merge"
+import { DirectoryTreeGridFooterRow, DirectoryTreeGridHeaderRow, DirectoryTreeGridRow } from "./DirectoryTreeGrid.tsx"
+import { DEFAULT_ITEM_HEIGHT, directoryTreeClasses, EXPAND_GLYPH_SIZE, getFileExtension, INDENT_SIZE, resolveEntryIcon, resolveExpandIcon } from "./entryRendering.tsx"
+import { buildNumericTemplate, clampHScroll, computeGridMetrics, DEFAULT_GRID_SCROLLBAR_WIDTH, flattenAllEntries } from "./gridUtils.ts"
+import { TreeLine } from "./TreeLine.tsx"
+import type { DirectoryEntry, DirectoryEntryItemProps, DirectoryTreeProps, DirectoryTreeVirtualScrollOptions, TreeLineGeometry, TreeLineGlyph, TreeLineItemInfo, TreeLineSegment } from "./types.ts"
+import { useEntryInteraction } from "./useEntryInteraction.ts"
+
+/**
+ * カスタムスクロールバー非表示スタイル
+ * Custom styles to hide scrollbar
+ */
+const scrollbarHideStyle: CSSProperties = {
+    msOverflowStyle: "none" /* IE and Edge */,
+    scrollbarWidth: "none" /* Firefox */,
+}
+
+/**
+ * Webkit スクロールバー非表示のスタイルを動的に適用
+ * Apply webkit scrollbar hiding styles dynamically
+ */
+const applyWebkitScrollbarHide = () => {
+    // 既存のスタイルタグがあるかチェック
+    let styleElement = document.getElementById("directory-tree-webkit-scrollbar-hide")
+
+    if (!styleElement) {
+        styleElement = document.createElement("style")
+        styleElement.id = "directory-tree-webkit-scrollbar-hide"
+        styleElement.textContent = ".directory-tree-container::-webkit-scrollbar { display: none; }"
+        document.head.appendChild(styleElement)
+    }
+}
+
+type FlattenedEntry = { entry: DirectoryEntry; indentLevel: number; parentIsLast: boolean[] }
+
+/** A flattened entry with its resolved row height. / 解決済みの行高を持つフラット化エントリ。 */
+type VirtualItem = FlattenedEntry & { rowHeight: number }
+
+type TreeTraversalResult = {
+    flatItems: FlattenedEntry[]
+    lineItems: TreeLineItemInfo[]
+    maxIndent: number
+}
+
+/**
+ * @function collectTreeData
+ * @description Traverses directory entries to build flattened items and tree line metadata.
+ *              ディレクトリエントリを走査してフラットなアイテムとツリーライン用メタデータを構築する。
+ */
+const collectTreeData = (entries: DirectoryEntry[], resolver: (absolutePath: string, relativePath?: string) => boolean, includeTreeLines: boolean, removeRootIndent: boolean): TreeTraversalResult => {
+    const flatItems: FlattenedEntry[] = []
+    const lineItems: TreeLineItemInfo[] = []
+    let maxIndent = 0
+
+    const walk = (currentEntries: DirectoryEntry[], indentLevel: number, ancestorChain: boolean[]): void => {
+        for (let index = 0; index < currentEntries.length; index++) {
+            const entry = currentEntries[index]
+            const isLastChild = index === currentEntries.length - 1
+            const nextAncestorChain = [...ancestorChain, isLastChild]
+            const isDirectory = entry.children !== undefined
+            const isExpanded = isDirectory && resolver(entry.absolutePath, entry.relativePath)
+
+            let effectiveIndentLevel = indentLevel
+            let effectiveNextAncestorChain = nextAncestorChain
+            let effectiveAncestorChain = ancestorChain
+
+            if (removeRootIndent) {
+                effectiveIndentLevel = indentLevel - 1
+                effectiveNextAncestorChain = nextAncestorChain.slice(1)
+                effectiveAncestorChain = ancestorChain.slice(1)
+            }
+
+            flatItems.push({ entry, indentLevel: effectiveIndentLevel, parentIsLast: effectiveNextAncestorChain })
+
+            if (includeTreeLines) {
+                if (effectiveIndentLevel > maxIndent) {
+                    maxIndent = effectiveIndentLevel
+                }
+                lineItems.push({
+                    id: entry.absolutePath,
+                    name: entry.name,
+                    absolutePath: entry.absolutePath,
+                    indentLevel: effectiveIndentLevel,
+                    isLastChild,
+                    isDirectory,
+                    isExpanded,
+                    ancestorIsLast: [...effectiveAncestorChain],
+                    hideLines: removeRootIndent && indentLevel === 0,
+                })
+            }
+
+            if (isDirectory && isExpanded && entry.children) {
+                walk(entry.children, indentLevel + 1, nextAncestorChain)
+            }
+        }
+    }
+
+    walk(entries, 0, [])
+    return { flatItems, lineItems, maxIndent }
+}
+
+type RangeMetrics = {
+    renderStart: number
+    renderEnd: number
+    lookaheadEnd: number
+}
+
+/**
+ * @function findItemIndexAtOffset
+ * @description Binary-searches a cumulative offset table for the item covering a pixel position.
+ *              累積オフセット表を二分探索し、指定ピクセル位置を含むアイテムのインデックスを返す。
+ * @param offsets - 累積オフセット表 (長さ = アイテム数 + 1、offsets[i] が item i の上端)。
+ * @param position - ピクセル位置。
+ * @returns offsets[i] <= position を満たす最大の i (0..itemCount-1 にクランプ)。
+ */
+const findItemIndexAtOffset = (offsets: number[], position: number): number => {
+    const itemCount = offsets.length - 1
+    if (itemCount <= 0) return 0
+    let low = 0
+    let high = itemCount - 1
+    let result = 0
+    while (low <= high) {
+        const mid = (low + high) >>> 1
+        if (offsets[mid] <= position) {
+            result = mid
+            low = mid + 1
+        } else {
+            high = mid - 1
+        }
+    }
+    return result
+}
+
+/**
+ * @function computeRangeMetrics
+ * @description Calculates render range metrics for tree line drawing.
+ *              ツリーライン描画のためのレンダリング範囲指標を算出する。
+ *              itemOffsets を用いるため可変高さの行でも正しく機能する。
+ */
+const computeRangeMetrics = (itemCount: number, viewportHeight: number, overscanCount: number, renderingRange: { renderStart: number; renderEnd: number } | null, scrollPosition: number, itemOffsets: number[]): RangeMetrics => {
+    const fallbackStart = renderingRange?.renderStart ?? Math.max(0, findItemIndexAtOffset(itemOffsets, scrollPosition))
+    const fallbackEndByHeight = viewportHeight > 0 ? findItemIndexAtOffset(itemOffsets, scrollPosition + viewportHeight) + overscanCount : fallbackStart + overscanCount
+    const fallbackEnd = itemCount > 0 ? Math.min(itemCount - 1, Math.max(fallbackStart, fallbackEndByHeight)) : fallbackStart
+    const renderEnd = renderingRange?.renderEnd ?? fallbackEnd
+    const lookaheadEnd = itemCount > 0 ? Math.min(itemCount - 1, renderEnd + overscanCount) : renderEnd
+    return { renderStart: fallbackStart, renderEnd, lookaheadEnd }
+}
+
+/**
+ * Builds geometry data for the canvas based tree line renderer, including segments and glyphs.
+ *
+ * Canvas ベースのツリーラインレンダラ用に線分とグリフのジオメトリデータを構築する。
+ *
+ * @param items - ツリーラインアイテムの配列。
+ * @param itemHeights - 各アイテムの高さの配列 (items と同じ順序・長さ)。
+ * @param itemOffsets - 各アイテムの累積上端オフセット表 (長さ = items.length + 1)。
+ * @param segmentWidth - インデントセグメントの幅。
+ * @param includeGlyphs - グリフ情報を含めるかどうか。
+ * @param glyphSizeOverride - グリフサイズの上書き値。
+ * @returns セグメントおよびグリフの配列をまとめたジオメトリデータ。
+ */
+export const buildTreeLineGeometry = (items: TreeLineItemInfo[], itemHeights: number[], itemOffsets: number[], segmentWidth: number, includeGlyphs: boolean, glyphSizeOverride?: number): TreeLineGeometry => {
+    if (items.length === 0) {
+        return { segmentsByItem: [], glyphsByItem: [] }
+    }
+
+    const segmentsByItem: TreeLineSegment[][] = Array.from({ length: items.length }, () => [])
+    const glyphsByItem: TreeLineGlyph[][] = Array.from({ length: items.length }, () => [])
+    // グリフサイズは行ごとの高さから解決する（override があればそれを優先）。可変高さ行に対応するため行内で算出する。
+    const resolveGlyphSize = (rowHeight: number): number => {
+        if (!includeGlyphs) {
+            return 0
+        }
+        if (typeof glyphSizeOverride === "number" && Number.isFinite(glyphSizeOverride) && glyphSizeOverride > 0) {
+            return glyphSizeOverride
+        }
+        return Math.max(8, Math.min(segmentWidth * 0.9, rowHeight * 0.7))
+    }
+
+    const xOffset = 3
+
+    for (let itemIndex = 0; itemIndex < items.length; itemIndex++) {
+        const item = items[itemIndex]
+        if (item.hideLines) {
+            continue
+        }
+        const group: TreeLineSegment[] = []
+        const rowHeight = itemHeights[itemIndex] ?? 0
+        const yBase = itemOffsets[itemIndex] ?? 0
+        const yCenter = yBase + rowHeight / 2
+        const computedGlyphSize = resolveGlyphSize(rowHeight)
+        const iconGap = computedGlyphSize > 0 ? computedGlyphSize / 2 + 2 : segmentWidth / 1.5
+
+        for (let depth = 0; depth < item.indentLevel; depth++) {
+            const ancestorIsLast = item.ancestorIsLast[depth] ?? false
+            if (ancestorIsLast) {
+                continue
+            }
+
+            let drawVerticalLine = false
+            for (let forwardIndex = itemIndex; forwardIndex < items.length; forwardIndex++) {
+                const candidate = items[forwardIndex]
+                if (candidate.indentLevel > depth && candidate.ancestorIsLast.length > depth && !candidate.ancestorIsLast[depth]) {
+                    drawVerticalLine = true
+                    break
+                }
+                /* v8 ignore next 3 -- 到達不能: forwardIndex===itemIndex(自分自身)が上の条件を常に満たすため、この break には到達しない。 */
+                if (forwardIndex > itemIndex && candidate.indentLevel === depth) {
+                    break
+                }
+            }
+
+            if (drawVerticalLine) {
+                const x = depth * segmentWidth + segmentWidth / 2 + xOffset
+                group.push({
+                    key: `${item.id}-ancestor-${depth}`,
+                    x1: x,
+                    y1: yBase,
+                    x2: x,
+                    y2: yBase + rowHeight,
+                    itemIndex,
+                })
+            }
+        }
+
+        const connectorXBase = item.indentLevel * segmentWidth
+        const connectorX = connectorXBase + segmentWidth / 2 + xOffset
+
+        if (item.isDirectory) {
+            group.push({
+                key: `${item.id}-connector-top`,
+                x1: connectorX,
+                y1: yBase,
+                x2: connectorX,
+                y2: yCenter - iconGap,
+                itemIndex,
+            })
+        } else {
+            group.push({
+                key: `${item.id}-connector-top`,
+                x1: connectorX,
+                y1: yBase,
+                x2: connectorX,
+                y2: yCenter,
+                itemIndex,
+            })
+        }
+
+        if (!item.isDirectory && item.isLastChild) {
+            group.push({
+                key: `${item.id}-connector-horizontal`,
+                x1: connectorX,
+                y1: yCenter,
+                x2: connectorXBase + segmentWidth + xOffset,
+                y2: yCenter,
+                itemIndex,
+            })
+        }
+
+        if (!item.isLastChild) {
+            if (item.isDirectory) {
+                group.push({
+                    key: `${item.id}-connector-bottom`,
+                    x1: connectorX,
+                    y1: yCenter + iconGap,
+                    x2: connectorX,
+                    y2: yBase + rowHeight,
+                    itemIndex,
+                })
+            } else {
+                group.push({
+                    key: `${item.id}-connector-bottom`,
+                    x1: connectorX,
+                    y1: yCenter,
+                    x2: connectorX,
+                    y2: yBase + rowHeight,
+                    itemIndex,
+                })
+            }
+        }
+
+        segmentsByItem[itemIndex] = group
+
+        if (includeGlyphs && item.isDirectory) {
+            const size = computedGlyphSize
+            const centerX = connectorX
+            const centerY = yCenter
+            glyphsByItem[itemIndex] = [
+                {
+                    key: `${item.id}-glyph`,
+                    itemIndex,
+                    centerX,
+                    centerY,
+                    size,
+                    isExpanded: item.isExpanded,
+                },
+            ]
+        }
+    }
+
+    return { segmentsByItem, glyphsByItem }
+}
+
+/**
+ * @component DirectoryEntryItem
+ * @description Renders a single entry (file or directory) in the directory tree. Memoized for performance.
+ *              ディレクトリツリー内の単一エントリ (ファイルまたはディレクトリ) をレンダリングする。パフォーマンスのためにメモ化されている。
+ */
+const DirectoryEntryItem = memo<DirectoryEntryItemProps>(
+    ({
+        entry,
+        indentLevel,
+        rowHeight,
+        isDirOpen,
+        parentIsLast,
+        renderChildren = true,
+        expansion: { toggleDirectory, onToggleDirectoryRecursive },
+        selection: { onEntryClick, selectedPath, mode: selectionMode = "none", selectedItems, onSelectionChange },
+        visual: {
+            iconOverrides,
+            showExpandIcons = true,
+            showDirectoryIcons = true,
+            showFileIcons = true,
+            useCanvasExpandIcons = false,
+            expandIconSize,
+            highlightStyles,
+            entryClassName,
+            entryStyle,
+            nameClassName,
+            nameStyle,
+            directoryNameClassName,
+            directoryNameStyle,
+            fileNameClassName,
+            fileNameStyle,
+        },
+    }) => {
+        const [childrenToRender, setChildrenToRender] = useState<DirectoryEntry[] | null>(null)
+        const [isHovered, setIsHovered] = useState(false)
+
+        const isDirectory = entry.children !== undefined
+        const isExpanded = isDirectory && isDirOpen(entry.absolutePath)
+        const isSelected = entry.absolutePath === selectedPath
+        const isItemSelected = !isDirectory && selectedItems?.has(entry.absolutePath)
+        const extension = isDirectory ? undefined : getFileExtension(entry.name)
+
+        /**
+         * @effect Lazy Children Loading
+         * @description Loads children only when expanded to optimize rendering performance.
+         *              レンダリングパフォーマンス最適化のため、展開時のみ子要素を読み込む。
+         */
+        useEffect(() => {
+            setChildrenToRender(isExpanded && entry.children ? entry.children : null)
+        }, [isExpanded, entry.children])
+
+        const handleInteraction = useEntryInteraction({ entry, isDirectory, isExpanded, isItemSelected: Boolean(isItemSelected), selectionMode, onSelectionChange, onEntryClick, toggleDirectory, onToggleDirectoryRecursive })
+
+        const hoverClass = isHovered ? (highlightStyles?.hoverClassName !== undefined ? highlightStyles.hoverClassName : directoryTreeClasses.entryHover) : ""
+
+        const selectedClass = (() => {
+            if (isDirectory) {
+                if (isSelected) {
+                    return highlightStyles?.directorySelectedClassName !== undefined ? highlightStyles.directorySelectedClassName : directoryTreeClasses.entrySelected
+                }
+            } else {
+                if (isSelected || isItemSelected) {
+                    if (highlightStyles?.itemSelectedClassName !== undefined) {
+                        return highlightStyles.itemSelectedClassName
+                    }
+                    return twMerge(isSelected && directoryTreeClasses.entrySelected, isItemSelected && directoryTreeClasses.entryItemSelected)
+                }
+            }
+            return ""
+        })()
+
+        const entryClasses = twMerge(directoryTreeClasses.entry, hoverClass, selectedClass, entryClassName, entry.className)
+        const expandIconClasses = twMerge(directoryTreeClasses.expandIcon, (isSelected || isItemSelected) && directoryTreeClasses.expandIconSelected)
+        const typeIconClasses = twMerge(directoryTreeClasses.typeIcon, (isSelected || isItemSelected) && directoryTreeClasses.typeIconSelected)
+        const nameClasses = twMerge(directoryTreeClasses.name, nameClassName, isDirectory && directoryTreeClasses.nameDirectory, isDirectory && directoryNameClassName, !isDirectory && fileNameClassName, (isSelected || isItemSelected) && directoryTreeClasses.nameSelected)
+
+        const expandIconContent = resolveExpandIcon({ isDirectory, isExpanded, showExpandIcons, useCanvasExpandIcons, expandIconSize })
+        const resolvedIcon = (isDirectory ? showDirectoryIcons : showFileIcons) ? resolveEntryIcon({ entry, isDirectory, isExpanded, isSelected, isItemSelected: Boolean(isItemSelected), extension }, iconOverrides) : null
+
+        const customHighlightStyle = {
+            ...(isHovered ? highlightStyles?.hoverStyle : {}),
+            ...(isDirectory && isSelected ? highlightStyles?.directorySelectedStyle : {}),
+            ...(!isDirectory && (isSelected || isItemSelected) ? highlightStyles?.itemSelectedStyle : {}),
+        }
+
+        return (
+            <Fragment key={entry.absolutePath}>
+                <div
+                    className={entryClasses}
+                    style={{
+                        paddingLeft: `${Math.max(0, indentLevel * INDENT_SIZE)}px`,
+                        transform: indentLevel < 0 ? `translateX(${indentLevel * INDENT_SIZE}px)` : undefined,
+                        width: indentLevel < 0 ? `calc(100% + ${Math.abs(indentLevel * INDENT_SIZE)}px)` : undefined,
+                        height: `${rowHeight}px`,
+                        ...customHighlightStyle,
+                        ...entryStyle,
+                        ...entry.style,
+                    }}
+                    data-entry-type={isDirectory ? "directory" : "file"}
+                    data-entry-expanded={isDirectory ? String(isExpanded) : undefined}
+                    data-entry-selected={isSelected ? "true" : undefined}
+                    data-entry-item-selected={isItemSelected ? "true" : undefined}
+                    onClick={handleInteraction}
+                    onMouseEnter={() => setIsHovered(true)}
+                    onMouseLeave={() => setIsHovered(false)}
+                    onKeyDown={(e) => e.key === "Enter" && handleInteraction(e as unknown as MouseEvent<HTMLDivElement>)}
+                    tabIndex={0}
+                    role="treeitem"
+                    aria-expanded={isDirectory ? isExpanded : undefined}
+                    aria-label={`${entry.name} (${isDirectory ? "directory" : "file"})`}>
+                    {(showExpandIcons || useCanvasExpandIcons) && <span className={expandIconClasses}>{expandIconContent}</span>}
+                    {(isDirectory ? showDirectoryIcons : showFileIcons) && <span className={typeIconClasses}>{resolvedIcon}</span>}
+                    <span
+                        className={nameClasses}
+                        style={{
+                            ...nameStyle,
+                            ...(isDirectory ? directoryNameStyle : fileNameStyle),
+                        }}
+                        data-entry-type={isDirectory ? "directory" : "file"}
+                        data-entry-role="name">
+                        {entry.label ?? entry.name}
+                    </span>
+                </div>
+                {/* v8 ignore start -- 到達不能: DirectoryTree は常に renderChildren=false で描画し(仮想化)、本コンポーネントは非公開のため、この非仮想化の再帰描画経路は使われない。 */}
+                {isExpanded && childrenToRender && renderChildren && (
+                    <fieldset>
+                        {childrenToRender.map((child, index) => (
+                            <DirectoryEntryItem
+                                key={child.absolutePath}
+                                entry={child}
+                                indentLevel={indentLevel + 1}
+                                // 非仮想化の再帰描画では親行の高さを一様に流用する (DirectoryTree は renderChildren=false のため通常この経路は通らない)。
+                                rowHeight={rowHeight}
+                                isDirOpen={isDirOpen}
+                                parentIsLast={[...parentIsLast, index === childrenToRender.length - 1]}
+                                expansion={{ toggleDirectory, onToggleDirectoryRecursive }}
+                                selection={{ onEntryClick, selectedPath, mode: selectionMode, selectedItems, onSelectionChange }}
+                                visual={{
+                                    iconOverrides,
+                                    showExpandIcons,
+                                    showDirectoryIcons,
+                                    showFileIcons,
+                                    useCanvasExpandIcons,
+                                    expandIconSize,
+                                    highlightStyles,
+                                    entryClassName,
+                                    entryStyle,
+                                    nameClassName,
+                                    nameStyle,
+                                    directoryNameClassName,
+                                    directoryNameStyle,
+                                    fileNameClassName,
+                                    fileNameStyle,
+                                }}
+                            />
+                        ))}
+                    </fieldset>
+                )}
+                {/* v8 ignore stop */}
+            </Fragment>
+        )
+    },
+    (prev, next) => {
+        if (prev.entry !== next.entry) return false
+        const prevIsDir = prev.entry.children !== undefined
+        const nextIsDir = next.entry.children !== undefined
+        const prevExpanded = prevIsDir && prev.isDirOpen(prev.entry.absolutePath)
+        const nextExpanded = nextIsDir && next.isDirOpen(next.entry.absolutePath)
+
+        return (
+            prev.indentLevel === next.indentLevel &&
+            prev.rowHeight === next.rowHeight &&
+            prevExpanded === nextExpanded &&
+            prev.selection.selectedPath === next.selection.selectedPath &&
+            prev.selection.mode === next.selection.mode &&
+            prev.selection.selectedItems === next.selection.selectedItems &&
+            prev.visual.iconOverrides === next.visual.iconOverrides &&
+            prev.visual.showExpandIcons === next.visual.showExpandIcons &&
+            prev.visual.showDirectoryIcons === next.visual.showDirectoryIcons &&
+            prev.visual.showFileIcons === next.visual.showFileIcons &&
+            prev.visual.useCanvasExpandIcons === next.visual.useCanvasExpandIcons &&
+            prev.visual.expandIconSize === next.visual.expandIconSize &&
+            prev.visual.highlightStyles === next.visual.highlightStyles &&
+            prev.visual.entryClassName === next.visual.entryClassName &&
+            prev.visual.entryStyle === next.visual.entryStyle &&
+            prev.visual.nameClassName === next.visual.nameClassName &&
+            prev.visual.nameStyle === next.visual.nameStyle &&
+            prev.visual.directoryNameClassName === next.visual.directoryNameClassName &&
+            prev.visual.directoryNameStyle === next.visual.directoryNameStyle &&
+            prev.visual.fileNameClassName === next.visual.fileNameClassName &&
+            prev.visual.fileNameStyle === next.visual.fileNameStyle &&
+            prev.parentIsLast.length === next.parentIsLast.length &&
+            prev.parentIsLast.every((val, i) => val === next.parentIsLast[i])
+        )
+    },
+)
+DirectoryEntryItem.displayName = "DirectoryEntryItem"
+
+// TreeLine コンポーネントが使用する props の型は TreeLine.tsx からインポートされる
+
+/**
+ * @function getAllDescendantPaths
+ * @description Recursively gets all descendant directory paths for a given entry.
+ *              指定されたエントリのすべての子孫ディレクトリパスを再帰的に取得する。
+ * @param {DirectoryEntry} entry - The directory entry to start from. 開始点となるディレクトリのエントリ。
+ * @returns {string[]} An array of absolute paths of all descendant directories. すべての子孫ディレクトリの絶対パスの配列。
+ */
+const getAllDescendantPaths = (entry: DirectoryEntry): string[] => {
+    const paths: string[] = []
+    if (entry.children) {
+        for (const child of entry.children) {
+            if (child.type === "directory") {
+                paths.push(child.absolutePath)
+                paths.push(...getAllDescendantPaths(child))
+            }
+        }
+    }
+    return paths
+}
+
+/**
+ * @component DirectoryTree
+ * @description A component to display a directory tree structure. It allows navigation and selection of files.
+ *              ディレクトリツリー構造を表示するコンポーネント。ファイルのナビゲーションと選択が可能。
+ */
+export const DirectoryTree = ({
+    entries,
+    expansion: { toggle, isExpanded, expandMultiple, collapseMultiple, isPending, alwaysExpanded = false, doubleClickAction = "recursive" },
+    selection: { onEntryClick, selectedPath, mode: selectionMode = "none", selectedItems, onSelectionChange },
+    visual: {
+        className,
+        style,
+        lineColor = "#A0AEC0",
+        showTreeLines = true,
+        showExpandIcons = true,
+        showDirectoryIcons = true,
+        showFileIcons = true,
+        iconOverrides,
+        expandIconSize,
+        itemHeight = DEFAULT_ITEM_HEIGHT,
+        removeRootIndent = false,
+        highlightStyles,
+        entryClassName,
+        entryStyle,
+        nameClassName,
+        nameStyle,
+        directoryNameClassName,
+        directoryNameStyle,
+        fileNameClassName,
+        fileNameStyle,
+    } = {},
+    virtualScroll: virtualScrollOptions,
+    grid,
+}: DirectoryTreeProps) => {
+    const isGrid = grid !== undefined
+    const [isClient, setIsClient] = useState(false)
+    const containerRef = useRef<HTMLDivElement | null>(null)
+    const bodyRef = useRef<HTMLDivElement | null>(null)
+    const virtualScrollRef = useRef<VirtualScrollHandle>(null)
+    const [measuredViewportHeight, setMeasuredViewportHeight] = useState(0)
+    const [measuredWidth, setMeasuredWidth] = useState(0)
+    const [hscroll, setHscroll] = useState(0)
+    const [renderingRange, setRenderingRange] = useState<{ renderStart: number; renderEnd: number } | null>(null)
+
+    const {
+        overscanCount: userOverscanCount = 15,
+        className: virtualScrollClassName,
+        background: virtualScrollBackground,
+        onScroll: virtualScrollOnScroll,
+        onRangeChange: virtualScrollOnRangeChange,
+        initialScrollIndex,
+        initialScrollOffset,
+        callbackThrottleMs = 5,
+        contentInsets: virtualScrollContentInsets,
+        onItemFocus,
+        viewportHeightOverride,
+        scrollBarOptions,
+        behaviorOptions,
+    }: DirectoryTreeVirtualScrollOptions = virtualScrollOptions ?? {}
+
+    const [scrollPosition, setScrollPosition] = useState(typeof initialScrollOffset === "number" ? initialScrollOffset : 0)
+
+    const handleVirtualScroll = useCallback(
+        (position: number, totalHeight: number) => {
+            setScrollPosition(position)
+            virtualScrollOnScroll?.(position, totalHeight)
+        },
+        [virtualScrollOnScroll],
+    )
+
+    const handleRangeChange = useCallback(
+        (range: VirtualScrollRange) => {
+            const { renderingStartIndex: start, renderingEndIndex: end } = range
+            setRenderingRange((prev) => (prev && prev.renderStart === start && prev.renderEnd === end ? prev : { renderStart: start, renderEnd: end }))
+            virtualScrollOnRangeChange?.(range)
+        },
+        [virtualScrollOnRangeChange],
+    )
+
+    /**
+     * @effect Initial Scroll Sync
+     * @description Synchronizes the internal scroll position state with the provided initial offset.
+     *              提供された初期オフセットと内部スクロール位置状態を同期する。
+     */
+    useEffect(() => {
+        if (typeof initialScrollOffset === "number") setScrollPosition(initialScrollOffset)
+    }, [initialScrollOffset])
+
+    /**
+     * @effect Client Mount & Scrollbar Hide
+     * @description Sets client-side flag and injects styles to hide Webkit scrollbars.
+     *              クライアントサイドフラグを設定し、Webkit スクロールバーを非表示にするスタイルを注入する。
+     */
+    useEffect(() => {
+        setIsClient(true)
+        applyWebkitScrollbarHide()
+    }, [])
+
+    /**
+     * @effect Viewport Height Observer
+     * @description Monitors the container's height using ResizeObserver to update the virtual scroll viewport.
+     *              ResizeObserver を使用してコンテナの高さを監視し、仮想スクロールのビューポートを更新する。
+     */
+    useEffect(() => {
+        const container = containerRef.current
+        // In grid mode header/footer are siblings of the body, so the viewport height must come
+        // from the body region only — the whole container would over-count by their heights.
+        // grid モードではヘッダ/フッタが本体の兄弟なので、ビューポート高は本体領域のみから取る。
+        const heightTarget = isGrid ? bodyRef.current : container
+
+        const measure = () => {
+            if (container) {
+                const nextWidth = container.clientWidth
+                setMeasuredWidth((prev) => (Math.abs(prev - nextWidth) > 1 ? nextWidth : prev))
+            }
+            if (typeof viewportHeightOverride === "number") {
+                setMeasuredViewportHeight((prev) => (Math.abs(prev - viewportHeightOverride) > 1 ? viewportHeightOverride : prev))
+            } else if (heightTarget) {
+                const nextHeight = heightTarget.clientHeight
+                setMeasuredViewportHeight((prev) => (Math.abs(prev - nextHeight) > 1 ? nextHeight : prev))
+            }
+        }
+
+        if (!(container || heightTarget)) return setMeasuredViewportHeight(0)
+        measure()
+
+        const resizeObserver = new ResizeObserver(measure)
+        if (container) resizeObserver.observe(container)
+        if (heightTarget && heightTarget !== container) resizeObserver.observe(heightTarget)
+        return () => resizeObserver.disconnect()
+    }, [viewportHeightOverride, isGrid])
+
+    const viewportHeight = typeof viewportHeightOverride === "number" ? viewportHeightOverride : measuredViewportHeight
+
+    const safeIsExpanded = useCallback((path: string) => alwaysExpanded || (isClient ? isExpanded(path) : false), [isClient, isExpanded, alwaysExpanded])
+
+    const containerClasses = twMerge(directoryTreeClasses.container, isPending && directoryTreeClasses.containerPending, className)
+    const containerStyle = useMemo(
+        () => ({
+            ...scrollbarHideStyle,
+            ...(style ?? {}),
+            ...(typeof viewportHeightOverride === "number" ? { height: viewportHeightOverride, minHeight: viewportHeightOverride } : {}),
+        }),
+        [style, viewportHeightOverride],
+    )
+
+    /**
+     * @callback handleDirectoryDoubleClick
+     * @description Handles double-click actions on directories (recursive expand/collapse or toggle).
+     *              ディレクトリのダブルクリックアクション (再帰的展開/折りたたみ、または切り替え) を処理する。
+     */
+    const handleDirectoryDoubleClick = useCallback(
+        (entry: DirectoryEntry, overrideAction?: "toggle" | "recursive") => {
+            const allPaths = [entry.absolutePath, ...getAllDescendantPaths(entry)]
+            const action = overrideAction || doubleClickAction
+            const allExpanded = allPaths.every((path) => safeIsExpanded(path))
+
+            if (allExpanded) return collapseMultiple(allPaths)
+
+            const allCollapsed = allPaths.every((path) => !safeIsExpanded(path))
+            if (allCollapsed || action === "recursive") return expandMultiple(allPaths)
+            if (action === "toggle") return collapseMultiple(allPaths)
+
+            /* v8 ignore next -- 到達不能: doubleClickAction は "toggle" | "recursive" のみ(型で保証)。防御的フォールバック。 */
+            console.warn(`[DirectoryTree] Unknown double click action: ${action}. No action taken.`)
+        },
+        [safeIsExpanded, expandMultiple, collapseMultiple, doubleClickAction],
+    )
+
+    // `removeRootIndent` relies on a negative-indent translateX shift that conflicts with the
+    // frozen name column (which must start at x=0), so it is intentionally ignored in grid mode.
+    // grid モードでは名前列を x=0 に凍結するため、負インデントに依存する removeRootIndent は無効化する。
+    const effectiveRemoveRootIndent = isGrid ? false : removeRootIndent
+    const { flatItems, lineItems, maxIndent } = useMemo(() => collectTreeData(entries, safeIsExpanded, showTreeLines, effectiveRemoveRootIndent), [entries, safeIsExpanded, showTreeLines, effectiveRemoveRootIndent])
+
+    // 各行の高さを解決する。number ならそのまま、関数なら (entry, flatIndex) で算出する。
+    // 不正値 (NaN / Infinity / 0 / 負値) は既定高さにフォールバックし、オフセット表の単調性と CSS 高さの妥当性を保証する。
+    const virtualItems = useMemo<VirtualItem[]>(
+        () =>
+            flatItems.map((item, index) => {
+                const resolved = typeof itemHeight === "function" ? itemHeight(item.entry, index) : itemHeight
+                return { ...item, rowHeight: Number.isFinite(resolved) && resolved > 0 ? resolved : DEFAULT_ITEM_HEIGHT }
+            }),
+        [flatItems, itemHeight],
+    )
+
+    // ツリーライン幾何・可視範囲計算に用いる高さ配列と累積オフセット表 (offsets[i] が item i の上端)。
+    const itemHeights = useMemo(() => virtualItems.map((item) => item.rowHeight), [virtualItems])
+    const itemOffsets = useMemo(() => {
+        const offsets = new Array<number>(itemHeights.length + 1)
+        offsets[0] = 0
+        for (let index = 0; index < itemHeights.length; index++) {
+            offsets[index + 1] = offsets[index] + itemHeights[index]
+        }
+        return offsets
+    }, [itemHeights])
+
+    // VirtualScroll に渡す高さ取得関数。identity は itemHeights が変わったときだけ更新される。
+    const getItemHeight = useCallback((index: number) => virtualItems[index]?.rowHeight ?? DEFAULT_ITEM_HEIGHT, [virtualItems])
+
+    const treeLineGeometry = useMemo(
+        () => (!showTreeLines || lineItems.length === 0 ? { segmentsByItem: [], glyphsByItem: [] } : buildTreeLineGeometry(lineItems, itemHeights, itemOffsets, INDENT_SIZE, showTreeLines, expandIconSize ?? EXPAND_GLYPH_SIZE)),
+        [lineItems, itemHeights, itemOffsets, showTreeLines, expandIconSize],
+    )
+
+    const treeLineWidth = useMemo(() => (!showTreeLines || entries.length === 0 ? 0 : (maxIndent + 2) * INDENT_SIZE), [entries.length, maxIndent, showTreeLines])
+    const { renderStart, renderEnd, lookaheadEnd } = useMemo(
+        () => computeRangeMetrics(virtualItems.length, viewportHeight, userOverscanCount, renderingRange, scrollPosition, itemOffsets),
+        [virtualItems.length, viewportHeight, userOverscanCount, renderingRange, scrollPosition, itemOffsets],
+    )
+
+    const treeLineBackground = useMemo(() => {
+        if (!showTreeLines || treeLineWidth <= 0 || viewportHeight <= 0 || treeLineGeometry.segmentsByItem.length === 0) return null
+        return (
+            <div className="pointer-events-none absolute inset-0 z-0" aria-hidden="true">
+                <div className="absolute top-0 left-0" style={{ width: treeLineWidth, height: viewportHeight }}>
+                    <TreeLine
+                        segmentsByItem={treeLineGeometry.segmentsByItem}
+                        glyphsByItem={treeLineGeometry.glyphsByItem}
+                        itemHeight={itemHeights[0] ?? DEFAULT_ITEM_HEIGHT}
+                        width={treeLineWidth}
+                        viewportHeight={viewportHeight}
+                        scrollPosition={scrollPosition}
+                        color={lineColor}
+                        expandGlyphColor={lineColor}
+                        expandGlyphSize={expandIconSize ?? EXPAND_GLYPH_SIZE}
+                        renderStartIndex={renderStart}
+                        renderEndIndex={renderEnd}
+                        lookaheadEndIndex={lookaheadEnd}
+                    />
+                </div>
+            </div>
+        )
+    }, [treeLineWidth, viewportHeight, renderStart, renderEnd, lookaheadEnd, scrollPosition, treeLineGeometry, lineColor, showTreeLines, expandIconSize, itemHeights])
+
+    const getItem = useCallback((index: number) => virtualItems[index], [virtualItems])
+
+    // ===== TreeGrid (columns) mode derived values =====
+    const gridColumns = grid?.columns
+    // Align the header/footer spacer with the body's vertical scrollbar: default to the actual
+    // VirtualScroll scrollbar width so columns stay aligned even when a consumer customizes it.
+    const gridScrollBarWidth = grid?.scrollBarWidth ?? scrollBarOptions?.width ?? DEFAULT_GRID_SCROLLBAR_WIDTH
+    const gridMetrics = useMemo(() => (gridColumns ? computeGridMetrics({ measuredWidth, columns: gridColumns, scrollBarWidth: gridScrollBarWidth }) : null), [gridColumns, measuredWidth, gridScrollBarWidth])
+    const numericTemplate = useMemo(() => (gridColumns ? buildNumericTemplate(gridColumns) : ""), [gridColumns])
+    // Footer aggregates over ALL nodes (collapsed included); only compute when a footer is shown.
+    const allEntriesFlat = useMemo(() => (grid?.showFooter && gridColumns ? flattenAllEntries(entries) : []), [grid?.showFooter, gridColumns, entries])
+    const maxHScroll = gridMetrics?.maxHScroll ?? 0
+    // Re-clamp the horizontal offset when the layout shrinks (resize / column change).
+    useEffect(() => {
+        setHscroll((prev) => clampHScroll(prev, maxHScroll))
+    }, [maxHScroll])
+    const handleWheelHorizontal = useCallback((deltaX: number) => setHscroll((prev) => clampHScroll(prev + deltaX, maxHScroll)), [maxHScroll])
+    // Stable visual object so horizontal scrolling (which changes --dt-hscroll only) never churns the memoized rows.
+    const gridRowVisual = useMemo(
+        () => ({ iconOverrides, showExpandIcons, showDirectoryIcons, showFileIcons, useCanvasExpandIcons: showTreeLines, expandIconSize, highlightStyles }),
+        [iconOverrides, showExpandIcons, showDirectoryIcons, showFileIcons, showTreeLines, expandIconSize, highlightStyles],
+    )
+
+    const isEmpty = entries.length === 0
+
+    // The VirtualScroll element is memoized WITHOUT hscroll in its deps: a horizontal-scroll tick only
+    // updates the container's `--dt-hscroll` variable (the numeric tracks translate via CSS and the
+    // memoized rows are skipped), so the virtualized body is not re-rendered. It still recomputes on
+    // vertical scroll (via treeLineBackground) and on any data/selection/visual change.
+    const virtualScrollElement = useMemo(
+        () => (
+            <VirtualScroll
+                ref={virtualScrollRef}
+                itemCount={virtualItems.length}
+                getItem={getItem}
+                getItemHeight={getItemHeight}
+                viewportSize={viewportHeight}
+                overscanCount={userOverscanCount}
+                onScroll={handleVirtualScroll}
+                onRangeChange={handleRangeChange}
+                className={virtualScrollClassName}
+                onWheelHorizontal={isGrid ? handleWheelHorizontal : undefined}
+                background={
+                    <>
+                        {isGrid && gridMetrics ? (
+                            // Clip the connector-line canvas to the frozen name column so deep trees never bleed into the numeric region.
+                            <div className="pointer-events-none absolute top-0 left-0 z-0 h-full overflow-hidden" style={{ width: gridMetrics.nameWidth }} aria-hidden="true">
+                                {treeLineBackground}
+                            </div>
+                        ) : (
+                            treeLineBackground
+                        )}
+                        {virtualScrollBackground}
+                    </>
+                }
+                initialScrollIndex={initialScrollIndex}
+                initialScrollOffset={initialScrollOffset}
+                onItemFocus={onItemFocus}
+                callbackThrottleMs={callbackThrottleMs}
+                contentInsets={virtualScrollContentInsets}
+                scrollBarOptions={scrollBarOptions}
+                behaviorOptions={behaviorOptions}>
+                {(item) => {
+                    if (!item) return null
+                    if (isGrid && grid && gridMetrics) {
+                        return (
+                            <DirectoryTreeGridRow
+                                key={item.entry.absolutePath}
+                                entry={item.entry}
+                                indentLevel={item.indentLevel}
+                                rowHeight={item.rowHeight}
+                                isDirOpen={safeIsExpanded}
+                                columns={grid.columns}
+                                numericTemplate={numericTemplate}
+                                numericTotal={gridMetrics.numericTotal}
+                                nameWidth={gridMetrics.nameWidth}
+                                rowClassName={grid.rowClassName}
+                                selection={{ onEntryClick, selectedPath: selectedPath ?? null, mode: selectionMode, selectedItems, onSelectionChange }}
+                                expansion={{ toggleDirectory: toggle, onToggleDirectoryRecursive: handleDirectoryDoubleClick }}
+                                visual={gridRowVisual}
+                            />
+                        )
+                    }
+                    return (
+                        <DirectoryEntryItem
+                            key={item.entry.absolutePath}
+                            entry={item.entry}
+                            indentLevel={item.indentLevel}
+                            rowHeight={item.rowHeight}
+                            isDirOpen={safeIsExpanded}
+                            parentIsLast={item.parentIsLast}
+                            renderChildren={false}
+                            expansion={{ toggleDirectory: toggle, onToggleDirectoryRecursive: handleDirectoryDoubleClick }}
+                            selection={{ onEntryClick, selectedPath: selectedPath ?? null, mode: selectionMode, selectedItems, onSelectionChange }}
+                            visual={{
+                                iconOverrides,
+                                showExpandIcons,
+                                showDirectoryIcons,
+                                showFileIcons,
+                                useCanvasExpandIcons: showTreeLines,
+                                expandIconSize,
+                                highlightStyles,
+                                entryClassName,
+                                entryStyle,
+                                nameClassName,
+                                nameStyle,
+                                directoryNameClassName,
+                                directoryNameStyle,
+                                fileNameClassName,
+                                fileNameStyle,
+                            }}
+                        />
+                    )
+                }}
+            </VirtualScroll>
+        ),
+        [
+            virtualItems.length,
+            getItem,
+            getItemHeight,
+            viewportHeight,
+            userOverscanCount,
+            handleVirtualScroll,
+            handleRangeChange,
+            virtualScrollClassName,
+            isGrid,
+            handleWheelHorizontal,
+            gridMetrics,
+            treeLineBackground,
+            virtualScrollBackground,
+            initialScrollIndex,
+            initialScrollOffset,
+            onItemFocus,
+            callbackThrottleMs,
+            virtualScrollContentInsets,
+            scrollBarOptions,
+            behaviorOptions,
+            grid,
+            numericTemplate,
+            safeIsExpanded,
+            onEntryClick,
+            selectedPath,
+            selectionMode,
+            selectedItems,
+            onSelectionChange,
+            toggle,
+            handleDirectoryDoubleClick,
+            gridRowVisual,
+            iconOverrides,
+            showExpandIcons,
+            showDirectoryIcons,
+            showFileIcons,
+            showTreeLines,
+            expandIconSize,
+            highlightStyles,
+            entryClassName,
+            entryStyle,
+            nameClassName,
+            nameStyle,
+            directoryNameClassName,
+            directoryNameStyle,
+            fileNameClassName,
+            fileNameStyle,
+        ],
+    )
+
+    if (!(grid && gridMetrics)) {
+        if (isEmpty) return <div className={containerClasses} style={containerStyle} />
+        return (
+            <div ref={containerRef} className={containerClasses} style={containerStyle} role="tree">
+                {virtualScrollElement}
+            </div>
+        )
+    }
+
+    const showHeader = grid.showHeader ?? true
+    const showFooter = grid.showFooter ?? false
+    const gridContainerStyle = { ...containerStyle, "--dt-hscroll": `${hscroll}px` } as CSSProperties
+
+    return (
+        <div ref={containerRef} className={twMerge(containerClasses, "dt-grid")} style={gridContainerStyle} role="treegrid">
+            {showHeader && <DirectoryTreeGridHeaderRow columns={grid.columns} numericTemplate={numericTemplate} numericTotal={gridMetrics.numericTotal} nameWidth={gridMetrics.nameWidth} scrollBarWidth={gridScrollBarWidth} className={grid.headerClassName} />}
+            <div ref={bodyRef} className="dt-grid-body">
+                {!isEmpty && virtualScrollElement}
+            </div>
+            {maxHScroll > 0 && (
+                <div className="dt-grid-hscrollbar-row">
+                    <div className="dt-grid-scrollbar-spacer" style={{ width: gridMetrics.nameWidth }} aria-hidden="true" />
+                    <ScrollBar
+                        horizontal
+                        contentSize={gridMetrics.numericTotal}
+                        viewportSize={gridMetrics.numericVisible}
+                        scrollPosition={hscroll}
+                        scrollBarWidth={gridScrollBarWidth}
+                        onScroll={(next) => {
+                            const resolved = typeof next === "function" ? next(hscroll) : next
+                            const clamped = clampHScroll(resolved, maxHScroll)
+                            setHscroll(clamped)
+                            return clamped
+                        }}
+                    />
+                    <div className="dt-grid-scrollbar-spacer" style={{ width: gridScrollBarWidth }} aria-hidden="true" />
+                </div>
+            )}
+            {showFooter && (
+                <DirectoryTreeGridFooterRow columns={grid.columns} numericTemplate={numericTemplate} numericTotal={gridMetrics.numericTotal} nameWidth={gridMetrics.nameWidth} scrollBarWidth={gridScrollBarWidth} allEntries={allEntriesFlat} className={grid.footerClassName} />
+            )}
+        </div>
+    )
+}
+
+export { directoryTreeClasses }