@aiquants/directory-tree 3.0.4 → 3.1.0

package/src/entryRendering.tsx

@@ -0,0 +1,131 @@
+/**
+ * @module entryRendering
+ * @description Shared constants, class names and icon-resolution helpers used by both the classic
+ *              label row (DirectoryEntryItem) and the TreeGrid row (DirectoryTreeGridRow).
+ *              Extracted from DirectoryTree.tsx so the two row renderers can share them without a
+ *              circular import.
+ *              従来行と TreeGrid 行が共有する定数・クラス・アイコン解決ヘルパ。循環 import 回避のため分離。
+ */
+import { ChevronDownIcon, ChevronRightIcon, DocumentTextIcon, FolderIcon } from "@heroicons/react/24/solid"
+import { FileIcon } from "@phosphor-icons/react"
+import type { ReactNode } from "react"
+import { twMerge } from "tailwind-merge"
+import type { DirectoryTreeIconOverrides, DirectoryTreeIconRenderContext, DirectoryTreeIconRenderer } from "./types.ts"
+
+/** Default row height in px. / 各行の高さの既定値 (px)。 */
+export const DEFAULT_ITEM_HEIGHT = 20
+/** Indentation per depth level in px. / 1 階層あたりのインデント幅 (px)。 */
+export const INDENT_SIZE = 16
+/** Standard expand glyph size. / 展開アイコンの標準サイズ。 */
+export const EXPAND_GLYPH_SIZE = 12
+
+/**
+ * TailwindCSS v4 class names for DirectoryTree component.
+ * DirectoryTreeコンポーネント用の TailwindCSS v4 クラス名。
+ */
+export const directoryTreeClasses = {
+    container: "directory-tree-container relative h-full transition-opacity duration-300 overflow-y-hidden pb-[5px] pr-[3px]",
+    containerPending: "opacity-70",
+
+    entry: "directory-tree-entry flex items-center cursor-pointer relative select-none",
+
+    // ホバー時のスタイル（ライト/ダークモード対応）
+    entryHover: twMerge("directory-tree-entry--hover hover:bg-gray-400/15", "dark:hover:bg-gray-200/10"),
+
+    // 選択時のスタイル（ライト/ダークモード対応）
+    entrySelected: twMerge("directory-tree-entry--selected bg-blue-400/10", "dark:bg-blue-400/15"),
+
+    // アイテム選択時のスタイル（ライト/ダークモード対応）
+    entryItemSelected: twMerge("directory-tree-entry--item-selected bg-blue-400/20 shadow-[0_0_0_1px_rgba(59,130,246,0.3)]", "dark:bg-blue-400/25 dark:shadow-[0_0_0_1px_rgba(96,165,250,0.4)]"),
+
+    // アイコンのスタイル
+    expandIcon: twMerge("directory-tree-expand-icon w-5 h-5 flex-shrink-0 flex items-center justify-center", "text-gray-500", "dark:text-gray-400"),
+
+    expandIconSelected: twMerge("directory-tree-expand-icon--selected text-blue-700", "dark:text-blue-400"),
+
+    typeIcon: twMerge("directory-tree-type-icon w-5 h-5 flex-shrink-0 flex items-center justify-center", "text-gray-500", "dark:text-gray-400"),
+
+    typeIconSelected: twMerge("directory-tree-type-icon--selected text-blue-700", "dark:text-blue-400"),
+
+    // テキストのスタイル
+    name: twMerge("directory-tree-name overflow-hidden text-ellipsis whitespace-nowrap ml-1", "text-gray-700", "dark:text-gray-200"),
+
+    nameDirectory: "directory-tree-name--directory",
+
+    nameSelected: twMerge("directory-tree-name--selected text-blue-800 font-medium", "dark:text-blue-300"),
+}
+
+/**
+ * @function getFileExtension
+ * @description Extracts the extension from a filename. / ファイル名から拡張子を抽出する。
+ */
+export const getFileExtension = (filename: string): string => {
+    return filename.slice(((filename.lastIndexOf(".") - 1) >>> 0) + 2).toLowerCase()
+}
+
+export type ExpandIconParams = {
+    isDirectory: boolean
+    isExpanded: boolean
+    showExpandIcons: boolean
+    useCanvasExpandIcons: boolean
+    expandIconSize?: number
+}
+
+/**
+ * @function resolveExpandIcon
+ * @description Determines the expand icon node for a directory entry. / 展開アイコンノードを決定する。
+ */
+export const resolveExpandIcon = ({ isDirectory, isExpanded, showExpandIcons, useCanvasExpandIcons, expandIconSize }: ExpandIconParams): ReactNode => {
+    const style = expandIconSize ? { width: expandIconSize, height: expandIconSize } : undefined
+    const className = expandIconSize ? "" : "h-4 w-4"
+
+    if (!(showExpandIcons && isDirectory) || useCanvasExpandIcons) {
+        return <span className={className} style={style} aria-hidden="true" />
+    }
+    return isExpanded ? <ChevronDownIcon className={className} style={style} /> : <ChevronRightIcon className={className} style={style} />
+}
+
+/**
+ * Resolves a directory tree icon renderer into a ReactNode.
+ * ディレクトリツリーのアイコン描画設定を ReactNode に解決する関数。
+ */
+const sanitizeIcon = (node: unknown, path: string): ReactNode | null => {
+    if (node === null || node === undefined || typeof node === "boolean") return null
+    if (typeof node === "function") {
+        console.warn(`[DirectoryTree] Function returned by renderer for "${path}". Return a node.`)
+        return null
+    }
+    if (typeof node === "object") {
+        if ("then" in node) {
+            console.warn(`[DirectoryTree] Promise returned for "${path}". Not supported.`)
+            return null
+        }
+        if (Array.isArray(node)) {
+            const kids = node.map((c) => sanitizeIcon(c, path)).filter(Boolean)
+            return kids.length ? kids : null
+        }
+        const type = (node as { type?: { $$typeof?: symbol } }).type
+        if (type && type.$$typeof === Symbol.for("react.lazy")) {
+            console.warn(`[DirectoryTree] Lazy component for "${path}". Not supported.`)
+            return null
+        }
+    }
+    return node as ReactNode
+}
+
+/**
+ * Determines the icon to render for a directory entry.
+ * ディレクトリエントリに表示するアイコンを決定する関数。
+ */
+export const resolveEntryIcon = (ctx: DirectoryTreeIconRenderContext, overrides?: DirectoryTreeIconOverrides): ReactNode => {
+    const { entry, isDirectory, isExpanded, extension } = ctx
+    let target: ReactNode | DirectoryTreeIconRenderer | undefined
+
+    if (entry.icon !== undefined) target = entry.icon
+    else if (isDirectory) target = (isExpanded && overrides?.directoryExpanded) || overrides?.directory || <FolderIcon className="h-4 w-4" />
+    else if (extension && overrides?.fileByExtension?.[extension]) target = overrides.fileByExtension[extension]
+    else target = overrides?.file || (extension === "md" ? <DocumentTextIcon className="h-4 w-4" /> : <FileIcon className="h-4 w-4" />)
+
+    if (typeof target === "function") return sanitizeIcon(target(ctx), entry.absolutePath)
+    return sanitizeIcon(target, entry.absolutePath)
+}

package/src/gridUtils.ts

@@ -0,0 +1,88 @@
+/**
+ * @module gridUtils
+ * @description Pure helpers for the DirectoryTree TreeGrid (columns) mode. Kept free of DOM/React
+ *              so the layout math can be unit-tested in isolation.
+ *              TreeGrid（列）モード用の純粋ヘルパ。DOM/React 非依存で単体テスト可能に保つ。
+ */
+import type { DirectoryEntry, DirectoryTreeColumn } from "./types.ts"
+
+/** Default frozen width of the name (tree) column in px. / 名前列の既定凍結幅 (px)。 */
+export const DEFAULT_NAME_COLUMN_WIDTH = 240
+/** Default width of a numeric column in px. / 数値列の既定幅 (px)。 */
+export const DEFAULT_NUMERIC_COLUMN_WIDTH = 96
+/** Default vertical scrollbar width used to align header/footer with the body. / ヘッダ/フッタ整合用の既定縦バー幅。 */
+export const DEFAULT_GRID_SCROLLBAR_WIDTH = 12
+
+/** Resolves the effective width of a column, applying defaults. / 列の実効幅を既定込みで解決する。 */
+const resolveColumnWidth = (column: DirectoryTreeColumn | undefined, fallback: number): number => {
+    const width = column?.width
+    return typeof width === "number" && Number.isFinite(width) && width > 0 ? width : fallback
+}
+
+/**
+ * Builds the `grid-template-columns` string for the numeric (non-name) columns.
+ * 数値列（columns[1..]）の `grid-template-columns` 文字列を構築する。
+ *
+ * @returns e.g. `"96px 96px 120px"`. Empty string when there is no numeric column.
+ */
+export const buildNumericTemplate = (columns: DirectoryTreeColumn[]): string =>
+    columns
+        .slice(1)
+        .map((column) => `${resolveColumnWidth(column, DEFAULT_NUMERIC_COLUMN_WIDTH)}px`)
+        .join(" ")
+
+/** Metrics describing the frozen/scrollable split of a TreeGrid. / TreeGrid の凍結/可動分割を表す寸法。 */
+export type GridMetrics = {
+    /** Frozen width of the name column. / 名前列の凍結幅。 */
+    nameWidth: number
+    /** Total width of all numeric columns (the scrollable content width). / 数値列合計幅（可動コンテンツ幅）。 */
+    numericTotal: number
+    /** Visible width of the numeric region (viewport). / 数値領域の可視幅（ビューポート）。 */
+    numericVisible: number
+    /** Maximum horizontal scroll offset (>= 0). / 横スクロールの最大オフセット (>= 0)。 */
+    maxHScroll: number
+}
+
+/**
+ * Computes the frozen/scrollable layout metrics from the measured container width.
+ * 計測済みコンテナ幅から凍結/可動レイアウトの寸法を算出する。
+ *
+ * `numericVisible = measuredWidth - nameWidth - scrollBarWidth`, clamped to >= 0. This single
+ * source of truth keeps the body (reduced by the vertical scrollbar) aligned with the
+ * header/footer (which reserve an equal right-side spacer).
+ */
+export const computeGridMetrics = ({ measuredWidth, columns, scrollBarWidth = DEFAULT_GRID_SCROLLBAR_WIDTH }: { measuredWidth: number; columns: DirectoryTreeColumn[]; scrollBarWidth?: number }): GridMetrics => {
+    const nameWidth = resolveColumnWidth(columns[0], DEFAULT_NAME_COLUMN_WIDTH)
+    const numericTotal = columns.slice(1).reduce((sum, column) => sum + resolveColumnWidth(column, DEFAULT_NUMERIC_COLUMN_WIDTH), 0)
+    const safeWidth = Number.isFinite(measuredWidth) && measuredWidth > 0 ? measuredWidth : 0
+    const numericVisible = Math.max(0, safeWidth - nameWidth - Math.max(0, scrollBarWidth))
+    const maxHScroll = Math.max(0, numericTotal - numericVisible)
+    return { nameWidth, numericTotal, numericVisible, maxHScroll }
+}
+
+/** Clamps a horizontal scroll offset into `[0, maxHScroll]`. / 横スクロール量を [0, maxHScroll] に丸める。 */
+export const clampHScroll = (value: number, maxHScroll: number): number => {
+    if (!Number.isFinite(value)) return 0
+    if (value < 0) return 0
+    if (value > maxHScroll) return maxHScroll
+    return value
+}
+
+/**
+ * Depth-first flattens every node of the tree **regardless of expansion state** — used to feed
+ * column footers that total over all entries (including collapsed subtrees).
+ * 展開状態に依存せず全ノードを DFS で平坦化する。列フッタの全 entries 合計に使用。
+ */
+export const flattenAllEntries = (entries: DirectoryEntry[]): DirectoryEntry[] => {
+    const result: DirectoryEntry[] = []
+    const walk = (nodes: DirectoryEntry[]): void => {
+        for (const node of nodes) {
+            result.push(node)
+            if (node.children && node.children.length > 0) {
+                walk(node.children)
+            }
+        }
+    }
+    walk(entries)
+    return result
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Directory Tree Component Library
+ * @package @aiquants/directory-tree
+ *
+ * This module provides a comprehensive directory tree component for React applications.
+ * The component supports virtualization for performance, file selection, and theming.
+ *
+ * このモジュールは React アプリケーション用の包括的なディレクトリツリーコンポーネントを提供します。
+ * このコンポーネントはパフォーマンス向上のための仮想化、ファイル選択、およびテーマ設定をサポートしています。
+ */
+
+export { DirectoryTree, directoryTreeClasses } from "./DirectoryTree.tsx"
+export type {
+    DirectoryEntry,
+    DirectoryEntryItemProps,
+    DirectoryTreeClickEvent,
+    DirectoryTreeColumn,
+    DirectoryTreeGrid,
+    DirectoryTreeIconOverrides,
+    DirectoryTreeIconRenderContext,
+    DirectoryTreeIconRenderer,
+    DirectoryTreeProps,
+    DirectoryTreeState,
+    DirectoryTreeVirtualScrollOptions,
+    HighlightStyles,
+    ItemHeight,
+    TreeLineItemInfo,
+    TreeLineProps,
+    UseDirectoryTreeStateProps,
+} from "./types.ts"
+export { useDirectoryTreeState } from "./useDirectoryTreeState.ts"

package/src/logger.ts

@@ -0,0 +1,162 @@
+/**
+ * @module utils/logger
+ * @description Logger utility for consistent log management across the library.
+ * @description ライブラリ全体で一貫したログ管理を行うためのロガーユーティリティ。
+ */
+
+/**
+ * @enum LogLevel
+ * @description Log levels for filtering output.
+ * @description 出力をフィルタリングするためのログレベル。
+ */
+export enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    NONE = 4,
+}
+
+/**
+ * @interface ILogger
+ * @description Interface for a logger object compatible with Console.
+ * @description Console と互換性のあるロガーオブジェクトのインターフェース。
+ */
+export interface ILogger {
+    debug(message?: unknown, ...optionalParams: unknown[]): void
+    info(message?: unknown, ...optionalParams: unknown[]): void
+    warn(message?: unknown, ...optionalParams: unknown[]): void
+    error(message?: unknown, ...optionalParams: unknown[]): void
+}
+
+/**
+ * @class Logger
+ * @description A wrapper class for handling logging with levels and prefixes.
+ * @description レベルとプレフィックスを使用したログ記録を処理するためのラッパークラス。
+ */
+export class Logger implements ILogger {
+    private level: LogLevel
+    private prefix: string
+    private impl: ILogger
+
+    /**
+     * @constructor
+     * @param {LogLevel} [level=LogLevel.WARN] - The minimum log level to output.
+     * @param {string} [prefix="[fuzzy-search]"] - The prefix to add to all log messages.
+     * @param {ILogger} [impl=console] - The implementation to use for logging.
+     */
+    constructor(level: LogLevel = LogLevel.WARN, prefix: string = "[fuzzy-search]", impl: ILogger = console) {
+        this.level = level
+        this.prefix = prefix
+        this.impl = impl
+    }
+
+    private static instance: Logger = new Logger(LogLevel.WARN, "[fuzzy-search]")
+
+    /**
+     * @method setLevel
+     * @description Updates the current log level for the static instance.
+     * @description 静的インスタンスの現在のログレベルを更新します。
+     * @param {LogLevel} level - The new log level.
+     */
+    static setLevel(level: LogLevel): void {
+        Logger.instance.setLevel(level)
+    }
+
+    /**
+     * @method setLevel
+     * @description Updates the current log level.
+     * @description 現在のログレベルを更新します。
+     * @param {LogLevel} level - The new log level.
+     */
+    setLevel(level: LogLevel): void {
+        this.level = level
+    }
+
+    /**
+     * @method setImplementation
+     * @description Updates the logger implementation for the static instance.
+     * @description 静的インスタンスのロガーの実装を更新します。
+     * @param {ILogger} impl - The new logger implementation.
+     */
+    static setImplementation(impl: ILogger): void {
+        Logger.instance.setImplementation(impl)
+    }
+
+    /**
+     * @method setImplementation
+     * @description Updates the logger implementation.
+     * @description ロガーの実装を更新します。
+     * @param {ILogger} impl - The new logger implementation.
+     */
+    setImplementation(impl: ILogger): void {
+        this.impl = impl
+    }
+
+    /**
+     * @method setPrefix
+     * @description Updates the log prefix for the static instance.
+     * @description 静的インスタンスのログのプレフィックスを更新します。
+     * @param {string} prefix - The new prefix.
+     */
+    static setPrefix(prefix: string): void {
+        Logger.instance.setPrefix(prefix)
+    }
+
+    /**
+     * @method setPrefix
+     * @description Updates the log prefix.
+     * @description ログのプレフィックスを更新します。
+     * @param {string} prefix - The new prefix.
+     */
+    setPrefix(prefix: string): void {
+        this.prefix = prefix
+    }
+
+    private formatMessage(message: unknown): unknown[] {
+        if (typeof message === "string") {
+            return [`${this.prefix} ${message}`]
+        }
+        return [this.prefix, message]
+    }
+
+    static debug(message?: unknown, ...optionalParams: unknown[]): void {
+        Logger.instance.debug(message, ...optionalParams)
+    }
+
+    debug(message?: unknown, ...optionalParams: unknown[]): void {
+        if (this.level <= LogLevel.DEBUG) {
+            this.impl.debug(...this.formatMessage(message), ...optionalParams)
+        }
+    }
+
+    static info(message?: unknown, ...optionalParams: unknown[]): void {
+        Logger.instance.info(message, ...optionalParams)
+    }
+
+    info(message?: unknown, ...optionalParams: unknown[]): void {
+        if (this.level <= LogLevel.INFO) {
+            this.impl.info(...this.formatMessage(message), ...optionalParams)
+        }
+    }
+
+    static warn(message?: unknown, ...optionalParams: unknown[]): void {
+        Logger.instance.warn(message, ...optionalParams)
+    }
+
+    warn(message?: unknown, ...optionalParams: unknown[]): void {
+        if (this.level <= LogLevel.WARN) {
+            this.impl.warn(...this.formatMessage(message), ...optionalParams)
+        }
+    }
+
+    static error(message?: unknown, ...optionalParams: unknown[]): void {
+        Logger.instance.error(message, ...optionalParams)
+    }
+
+    error(message?: unknown, ...optionalParams: unknown[]): void {
+        if (this.level <= LogLevel.ERROR) {
+            this.impl.error(...this.formatMessage(message), ...optionalParams)
+        }
+    }
+}

package/src/styles/components.entry.css

@@ -0,0 +1,8 @@
+/*
+ * Artifact A: components-only CSS (Tailwind ホスト向け).
+ * 手書き .dt-* コンポーネントクラスのみ。virtualscroll CSS は埋め込まない
+ * (ホストが @aiquants/virtualscroll の Artifact A を別途 import するため。二重同梱を回避)。
+ * :root テーマ変数・ユーティリティ・preflight を含まない。
+ */
+@import "tailwindcss/theme.css" theme(reference);
+@import "./directory-tree.css";

package/src/styles/directory-tree.css

@@ -0,0 +1,89 @@
+@layer utilities {
+  /* ===== TreeGrid (columns) mode ===== */
+  /* Frozen name column on the left; numeric columns scroll horizontally via the shared
+     --dt-hscroll custom property. Header / body rows / footer all read the same variable so
+     they stay perfectly aligned without any per-row React re-render.
+     左に凍結した名前列、数値列は共有変数 --dt-hscroll で横スクロール。ヘッダ/本体/フッタが同一変数を
+     参照するため、行の再レンダー無しで整列を保つ。 */
+
+  .dt-grid {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+  }
+
+  /* The virtualized body region. Its height (not the whole container's) is what the viewport
+     measurement must use, so header/footer are excluded. / 計測対象はこの本体領域の高さ。 */
+  .dt-grid-body {
+    position: relative;
+    flex: 1 1 0%;
+    min-height: 0;
+  }
+
+  .dt-grid-header,
+  .dt-grid-footer,
+  .dt-grid-row,
+  .dt-grid-hscrollbar-row {
+    display: flex;
+    align-items: stretch;
+  }
+
+  /* Frozen name cell/header/footer: fixed width, above the numeric track (z-index), clips its
+     own overflow. / 凍結名前セル: 固定幅・数値トラックより前面・自身をクリップ。 */
+  .dt-grid-name-cell,
+  .dt-grid-name-header,
+  .dt-grid-name-footer {
+    position: relative;
+    z-index: 1;
+    flex-shrink: 0;
+    display: flex;
+    align-items: center;
+    overflow: hidden;
+  }
+
+  /* Scrollable numeric region: a per-element viewport clips the translated track's overflow on
+     both sides (so it never slides under the frozen name cell). / 行ごとのビューポートで両端クリップ。 */
+  .dt-grid-numeric-viewport {
+    position: relative;
+    flex: 1 1 0%;
+    overflow: hidden;
+  }
+
+  .dt-grid-numeric-track {
+    display: grid;
+    transform: translateX(calc(-1 * var(--dt-hscroll, 0px)));
+    will-change: transform;
+  }
+
+  .dt-grid-cell {
+    display: flex;
+    align-items: center;
+    padding: 0 8px;
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+  }
+
+  /* Right-aligned / centered numeric cells. / 右寄せ・中央寄せセル。 */
+  .dt-grid-cell--right {
+    justify-content: flex-end;
+    text-align: right;
+  }
+
+  .dt-grid-cell--center {
+    justify-content: center;
+    text-align: center;
+  }
+
+  .dt-grid-name-label {
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+  }
+
+  /* Fixed-width spacers used to keep the horizontal scrollbar aligned with the numeric viewport
+     (left = name width, right = vertical scrollbar width). / 横バー整合用スペーサ。 */
+  .dt-grid-scrollbar-spacer {
+    flex-shrink: 0;
+  }
+}

package/src/styles/standalone.entry.css

@@ -0,0 +1,12 @@
+/*! @aiquants/directory-tree standalone CSS — 非 Tailwind ホスト専用。ホストの Tailwind ビルドと混在させないこと */
+/*
+ * Artifact B: 自己完結スタンドアロン. 非 Tailwind ホストの利便のため peer の
+ * @aiquants/virtualscroll CSS も同梱する (Tailwind ホストは Artifact A を使うので二重にならない)。
+ */
+@layer theme, base, components, utilities;
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/utilities.css" layer(utilities) source(none);
+@import "@aiquants/virtualscroll/styles/virtualscroll.css" layer(components);
+@import "./directory-tree.css" layer(components);
+@source "../**/*.{ts,tsx}";
+@custom-variant dark (&:where(.dark, .dark *));