momoi-explorer 0.8.0

package/dist/react.d.ts

@@ -0,0 +1,499 @@
+import * as React$1 from 'react';
+import React__default, { ReactNode } from 'react';
+
+/**
+ * ファイルシステムへのアクセスを抽象化するアダプタインターフェース。
+ * ユーザーはこのインターフェースを実装してcreateFileTreeに渡す。
+ * `readDir` のみ必須。その他のメソッドはオプションで、対応する機能が有効になる。
+ *
+ * @example
+ * ```ts
+ * import { FileSystemAdapter } from 'momoi-explorer'
+ * import fs from 'node:fs/promises'
+ * import path from 'node:path'
+ *
+ * const adapter: FileSystemAdapter = {
+ *   async readDir(dirPath) {
+ *     const entries = await fs.readdir(dirPath, { withFileTypes: true })
+ *     return entries.map(e => ({
+ *       name: e.name,
+ *       path: path.join(dirPath, e.name),
+ *       isDirectory: e.isDirectory(),
+ *     }))
+ *   },
+ *   async rename(oldPath, newPath) { await fs.rename(oldPath, newPath) },
+ *   async delete(paths) { for (const p of paths) await fs.rm(p, { recursive: true }) },
+ * }
+ * ```
+ */
+interface FileSystemAdapter {
+    /**
+     * ディレクトリの中身を読み取る。唯一の必須メソッド。
+     * @param path - 読み取るディレクトリの絶対パス
+     * @returns ディレクトリ内のFileEntryの配列
+     */
+    readDir(path: string): Promise<FileEntry[]>;
+    /**
+     * ファイルまたはフォルダをリネームする。
+     * 実装するとUI上でリネーム操作が可能になる。
+     * @param oldPath - リネーム前の絶対パス
+     * @param newPath - リネーム後の絶対パス
+     */
+    rename?(oldPath: string, newPath: string): Promise<void>;
+    /**
+     * ファイルまたはフォルダを削除する。
+     * 実装すると選択アイテムの削除操作が可能になる。
+     * @param paths - 削除対象の絶対パスの配列
+     */
+    delete?(paths: string[]): Promise<void>;
+    /**
+     * ファイルを新規作成する。
+     * 実装するとUI上でファイル作成操作が可能になる。
+     * @param parentPath - 作成先の親ディレクトリの絶対パス
+     * @param name - 新規ファイル名
+     */
+    createFile?(parentPath: string, name: string): Promise<void>;
+    /**
+     * フォルダを新規作成する。
+     * 実装するとUI上でフォルダ作成操作が可能になる。
+     * @param parentPath - 作成先の親ディレクトリの絶対パス
+     * @param name - 新規フォルダ名
+     */
+    createDir?(parentPath: string, name: string): Promise<void>;
+    /**
+     * ファイル変更監視を開始する。
+     * 生イベントを投げるだけでOK。デバウンス・合体・スロットリングはコアが行う。
+     * @param path - 監視するディレクトリの絶対パス
+     * @param callback - 生イベントを受け取るコールバック
+     * @returns 監視を停止するunwatch関数
+     */
+    watch?(path: string, callback: (events: RawWatchEvent[]) => void): () => void;
+}
+/**
+ * ファイルまたはフォルダを表すエントリ。
+ * `readDir` の戻り値として使用される基本データ型。
+ */
+interface FileEntry {
+    /** ファイル名（拡張子含む） */
+    name: string;
+    /** 絶対パス */
+    path: string;
+    /** ディレクトリならtrue */
+    isDirectory: boolean;
+    /**
+     * ユーザー拡張用のメタデータ。
+     * gitStatus, iconHint 等、任意のデータを格納できる。
+     */
+    meta?: Record<string, unknown>;
+}
+/**
+ * コア内部で使用されるツリーノード。FileEntryにツリー構造の情報を追加したもの。
+ * flatList内のFlatNode.nodeとしても参照される。
+ */
+interface TreeNode extends FileEntry {
+    /** ルートからの深さ（ルート直下 = 0） */
+    depth: number;
+    /** 子ノード。ディレクトリで未読み込みの場合はundefined */
+    children?: TreeNode[];
+    /** 子ノードが読み込み済みかどうか */
+    childrenLoaded: boolean;
+}
+/**
+ * 仮想スクロール用のフラットリスト要素。
+ * ツリーを展開状態に基づいて一次元配列に変換したもの。
+ */
+interface FlatNode {
+    /** 対応するツリーノード */
+    node: TreeNode;
+    /** 表示上の深さ（インデント計算に使用） */
+    depth: number;
+}
+/** インライン新規作成の状態 */
+interface CreatingState {
+    /** 新規アイテムを作成する親ディレクトリのパス */
+    parentPath: string;
+    /** ファイルかフォルダか */
+    isDirectory: boolean;
+    /** この位置の直後に入力行を表示する。未指定なら親の子の先頭（フォルダ選択時）or末尾（選択なし時） */
+    insertAfterPath?: string;
+}
+/**
+ * ツリー全体の現在状態。subscribeで購読可能。
+ * 不変(immutable)として扱い、変更時は新しいオブジェクトが生成される。
+ */
+interface TreeState {
+    /** ルートディレクトリの絶対パス */
+    rootPath: string;
+    /** ルート直下のツリーノード配列 */
+    rootNodes: TreeNode[];
+    /** 現在展開中のディレクトリパスのセット */
+    expandedPaths: Set<string>;
+    /** 現在選択中のパスのセット */
+    selectedPaths: Set<string>;
+    /** 範囲選択の起点パス（Shift+Click用） */
+    anchorPath: string | null;
+    /** 現在リネーム中のパス。nullならリネームモードではない */
+    renamingPath: string | null;
+    /** インライン新規作成の状態。nullなら作成モードではない */
+    creatingState: CreatingState | null;
+    /** 現在の検索クエリ。nullなら検索なし */
+    searchQuery: string | null;
+    /** 仮想スクロール用のフラットリスト（展開・検索状態を反映） */
+    flatList: FlatNode[];
+}
+/**
+ * アダプタのwatchから来る生のファイル監視イベント。
+ * renameイベントはnewPathを持つ。コアが合体処理を行う。
+ */
+interface RawWatchEvent {
+    /** イベント種別 */
+    type: 'create' | 'modify' | 'delete' | 'rename';
+    /** 対象パス（renameの場合はリネーム前のパス） */
+    path: string;
+    /** renameの場合のリネーム後パス */
+    newPath?: string;
+    /** 対象がディレクトリかどうか */
+    isDirectory: boolean;
+}
+/**
+ * コア内部で合体処理後のイベント。
+ * renameはdelete+createに分解され、同一パスのイベントは合体される。
+ */
+interface WatchEvent {
+    /** イベント種別（renameは含まない） */
+    type: 'create' | 'modify' | 'delete';
+    /** 対象パス */
+    path: string;
+    /** 対象がディレクトリかどうか */
+    isDirectory: boolean;
+}
+/**
+ * ツリー操作や外部変更をUI層に通知するためのイベント型。
+ * `FileTreeOptions.onEvent` で購読できる。
+ *
+ * - `expand` / `collapse` - ディレクトリの展開/折りたたみ
+ * - `select` - 選択変更
+ * - `open` - ファイルを開く
+ * - `rename` - リネーム完了
+ * - `delete` - 削除完了
+ * - `create` - ファイル/フォルダ作成完了
+ * - `refresh` - ツリーのリフレッシュ
+ * - `external-change` - ファイル監視による外部変更検出
+ */
+type TreeEvent = {
+    type: 'expand';
+    path: string;
+} | {
+    type: 'collapse';
+    path: string;
+} | {
+    type: 'select';
+    paths: string[];
+} | {
+    type: 'open';
+    path: string;
+} | {
+    type: 'rename';
+    oldPath: string;
+    newPath: string;
+} | {
+    type: 'delete';
+    paths: string[];
+} | {
+    type: 'create';
+    parentPath: string;
+    name: string;
+    isDirectory: boolean;
+} | {
+    type: 'refresh';
+    path?: string;
+} | {
+    type: 'external-change';
+    changes: WatchEvent[];
+};
+/**
+ * ファイル監視の動作設定。
+ * createFileTreeのoptionsで指定する。
+ */
+interface WatchOptions {
+    /** デバウンス時間(ms)。デフォルト: 75 (VSCode準拠) */
+    debounceMs?: number;
+    /** イベント合体を行うか。デフォルト: true */
+    coalesce?: boolean;
+    /** スロットリング設定。大量イベント発生時にチャンク分割する */
+    throttle?: {
+        /** 一度に処理するイベント上限。デフォルト: 500 */
+        maxChunkSize: number;
+        /** チャンク間の休止時間(ms)。デフォルト: 200 */
+        delayMs: number;
+    };
+}
+/**
+ * {@link createFileTree} の初期化オプション。
+ */
+interface FileTreeOptions {
+    /** ファイルシステムアダプタ（必須） */
+    adapter: FileSystemAdapter;
+    /** ツリーのルートディレクトリの絶対パス */
+    rootPath: string;
+    /** カスタムソート関数。未指定時はフォルダ優先・名前昇順 */
+    sort?: (a: FileEntry, b: FileEntry) => number;
+    /** カスタムフィルタ関数。falseを返すエントリは非表示になる */
+    filter?: (entry: FileEntry) => boolean;
+    /** ファイル監視のオプション */
+    watchOptions?: WatchOptions;
+    /** ツリー操作イベントのコールバック */
+    onEvent?: (event: TreeEvent) => void;
+}
+/**
+ * ヘッドレスファイルツリーのメインコントローラ。
+ * {@link createFileTree} から返される。状態購読・ツリー操作・編集・検索などの全APIを提供する。
+ */
+interface FileTreeController {
+    /**
+     * 現在のツリー状態を取得する。
+     * @returns 現在のTreeState
+     */
+    getState(): TreeState;
+    /**
+     * 状態変更を購読する。状態が変わるたびにlistenerが呼ばれる。
+     * @param listener - 状態変更時に呼ばれるコールバック
+     * @returns 購読解除関数
+     */
+    subscribe(listener: (state: TreeState) => void): () => void;
+    /**
+     * ルートディレクトリを読み込み、ツリーを初期化する。
+     * ファイル監視もここで開始される。最初に必ず呼ぶこと。
+     */
+    loadRoot(): Promise<void>;
+    /**
+     * 指定パスのディレクトリを展開する。未読み込みなら子を読み込む。
+     * @param path - 展開するディレクトリの絶対パス
+     */
+    expand(path: string): Promise<void>;
+    /**
+     * 指定パスのディレクトリを折りたたむ。
+     * @param path - 折りたたむディレクトリの絶対パス
+     */
+    collapse(path: string): void;
+    /**
+     * 展開/折りたたみをトグルする。
+     * @param path - 対象ディレクトリの絶対パス
+     */
+    toggleExpand(path: string): Promise<void>;
+    /**
+     * 指定パスまでの祖先ディレクトリをすべて展開する。
+     * ファイルを可視状態にしたい場合に使用する。
+     * @param path - 表示したいノードの絶対パス
+     */
+    expandTo(path: string): Promise<void>;
+    /**
+     * ノードを選択する。
+     * @param path - 選択するノードの絶対パス
+     * @param mode - 選択モード。'replace'=単一選択、'toggle'=Ctrl+Click、'range'=Shift+Click
+     */
+    select(path: string, mode?: 'replace' | 'toggle' | 'range'): void;
+    /** flatList内の全ノードを選択する */
+    selectAll(): void;
+    /** 選択をすべて解除する */
+    clearSelection(): void;
+    /**
+     * リネームモードを開始する。UIはこの状態を検知してインライン編集UIを表示する。
+     * @param path - リネーム対象の絶対パス
+     */
+    startRename(path: string): void;
+    /**
+     * リネームを確定する。adapter.renameが呼ばれ、親ディレクトリがリフレッシュされる。
+     * @param newName - 新しいファイル名（パスではなく名前のみ）
+     */
+    commitRename(newName: string): Promise<void>;
+    /** リネームをキャンセルする */
+    cancelRename(): void;
+    /**
+     * インライン新規作成モードを開始する。親ディレクトリを展開し、入力行を表示する。
+     * @param parentPath - 作成先の親ディレクトリの絶対パス
+     * @param isDirectory - フォルダを作成する場合はtrue
+     * @param insertAfterPath - この位置の直後に入力行を表示する
+     */
+    startCreate(parentPath: string, isDirectory: boolean, insertAfterPath?: string): Promise<void>;
+    /**
+     * インライン新規作成を確定する。adapter.createFile/createDirが呼ばれる。
+     * @param name - 新規ファイル/フォルダ名
+     */
+    commitCreate(name: string): Promise<void>;
+    /** インライン新規作成をキャンセルする */
+    cancelCreate(): void;
+    /**
+     * ファイルを新規作成する。adapter.createFileが呼ばれる。
+     * @param parentPath - 作成先の親ディレクトリの絶対パス
+     * @param name - 新規ファイル名
+     */
+    createFile(parentPath: string, name: string): Promise<void>;
+    /**
+     * フォルダを新規作成する。adapter.createDirが呼ばれる。
+     * @param parentPath - 作成先の親ディレクトリの絶対パス
+     * @param name - 新規フォルダ名
+     */
+    createDir(parentPath: string, name: string): Promise<void>;
+    /** 選択中のアイテムをすべて削除する。adapter.deleteが呼ばれる */
+    deleteSelected(): Promise<void>;
+    /**
+     * ツリーを再読み込みする。展開状態は保持される。
+     * @param path - リフレッシュ対象のディレクトリ。省略時はルート全体
+     */
+    refresh(path?: string): Promise<void>;
+    /**
+     * ファジー検索クエリを設定する。flatListがフィルタされマッチしたノードのみ表示される。
+     * @param query - 検索文字列。nullで検索解除
+     */
+    setSearchQuery(query: string | null): void;
+    /**
+     * ツリー配下の全ファイルを再帰的に収集する。
+     * fuzzyFind等で全ファイル検索を行う際の入力データとして使用する。
+     * @returns 全FileEntryの配列
+     */
+    collectAllFiles(): Promise<FileEntry[]>;
+    /**
+     * フィルタ関数を動的に変更する。既存ノードにも即座に適用される。
+     * @param fn - フィルタ関数。nullでフィルタ解除
+     */
+    setFilter(fn: ((entry: FileEntry) => boolean) | null): void;
+    /**
+     * ソート関数を動的に変更する。既存ノードにも即座に適用される。
+     * @param fn - ソート関数。nullでデフォルトソートに戻す
+     */
+    setSort(fn: ((a: FileEntry, b: FileEntry) => number) | null): void;
+    /** コントローラを破棄する。ファイル監視を停止し、購読をすべて解除する */
+    destroy(): void;
+}
+
+/** {@link TreeProvider} に渡すprops */
+interface TreeProviderProps {
+    /** ファイルシステム操作の実装 */
+    adapter: FileSystemAdapter;
+    /** ツリーのルートディレクトリパス */
+    rootPath: string;
+    /** ファイル/フォルダのソート関数 */
+    sort?: FileTreeOptions['sort'];
+    /** 表示対象を絞り込むフィルタ関数 */
+    filter?: FileTreeOptions['filter'];
+    /** ファイル監視の設定 */
+    watchOptions?: FileTreeOptions['watchOptions'];
+    /** ツリー操作イベントのコールバック */
+    onEvent?: (event: TreeEvent) => void;
+    children: ReactNode;
+}
+/**
+ * ファイルツリーのコンテキストプロバイダー。
+ * 内部で `createFileTree` を呼び出し、マウント時に `loadRoot` でルートを読み込む。
+ * 子コンポーネントから `useFileTree` / `useTreeNode` でツリー状態にアクセスできる。
+ */
+declare function TreeProvider({ adapter, rootPath, sort, filter, watchOptions, onEvent, children, }: TreeProviderProps): React__default.JSX.Element;
+
+/** TreeProvider が提供するコンテキスト値 */
+interface TreeContextValue {
+    /** ツリー操作用コントローラ */
+    controller: FileTreeController;
+    /** 現在のツリー状態 */
+    state: TreeState;
+}
+/** @internal ツリーコンテキスト。通常は直接使わず `useTreeContext` 経由で利用する */
+declare const TreeContext: React$1.Context<TreeContextValue | null>;
+/**
+ * TreeProvider のコンテキストを取得する。
+ * TreeProvider の外で使用すると Error をスローする。
+ * @returns ツリーのコントローラと状態
+ */
+declare function useTreeContext(): TreeContextValue;
+
+/** {@link useFileTree} の戻り値。ツリー状態の全フィールドに加えコントローラを含む */
+interface UseFileTreeResult extends TreeState {
+    /** ツリー操作用コントローラ */
+    controller: FileTreeController;
+}
+/**
+ * ツリー全体の状態とコントローラを返すフック。
+ * TreeProvider 内で使用すること。
+ * @returns ツリー状態（flatList, expandedPaths 等）とコントローラ
+ */
+declare function useFileTree(): UseFileTreeResult;
+
+/** {@link useTreeNode} の戻り値 */
+interface UseTreeNodeResult {
+    /** ノード本体 */
+    node: TreeNode;
+    /** ディレクトリが展開されているか */
+    isExpanded: boolean;
+    /** 選択されているか */
+    isSelected: boolean;
+    /** リネーム中か */
+    isRenaming: boolean;
+    /** ツリー上のネスト深度 */
+    depth: number;
+}
+/**
+ * 指定パスのノード状態を返すフック。
+ * TreeProvider 内で使用すること。パスが見つからない場合は `null` を返す。
+ * @param path - 取得したいノードのファイルパス
+ * @returns ノードの状態。パスが見つからなければ `null`
+ */
+declare function useTreeNode(path: string): UseTreeNodeResult | null;
+
+/** コンテキストメニューの表示状態 */
+interface ContextMenuState {
+    /** メニューが表示されているか */
+    isVisible: boolean;
+    /** メニューのX座標（clientX） */
+    x: number;
+    /** メニューのY座標（clientY） */
+    y: number;
+    /** 右クリック対象のファイルパス */
+    targetPath: string | null;
+}
+/** {@link useContextMenu} の戻り値 */
+interface UseContextMenuResult extends ContextMenuState {
+    /** 指定位置にコンテキストメニューを表示する */
+    show(e: React.MouseEvent, targetPath: string): void;
+    /** コンテキストメニューを閉じる */
+    hide(): void;
+}
+/**
+ * 右クリックメニューの表示位置・表示状態を管理するフック。
+ * @returns メニュー状態と表示/非表示の操作関数
+ */
+declare function useContextMenu(): UseContextMenuResult;
+
+/**
+ * InputService（momoi-keybind）を受け取り、エクスプローラーのコマンドハンドラーを登録する。
+ * momoi-keybindが無い場合は使わなくてOK。
+ *
+ * @param inputService - momoi-keybindのInputServiceインスタンス。nullならスキップ
+ * @param options - コマンド実行時の追加処理
+ */
+declare function useExplorerKeybindings(inputService: InputServiceLike | null, options?: {
+    onCopyPath?: (paths: string[]) => void;
+}): void;
+/**
+ * momoi-keybindのInputServiceの最小インターフェース。
+ * momoi-keybindに直接依存せず、duck typingで受け入れる。
+ */
+interface InputServiceLike {
+    registerCommand(command: string, handler: (args?: unknown) => void): () => void;
+    setContext(key: string, value: unknown): void;
+    deleteContext(key: string): void;
+}
+
+/**
+ * エクスプローラーのフォーカス状態をmomoi-keybindのコンテキストに連動させるhook。
+ * 返されたpropsをエクスプローラーのルート要素に渡す。
+ *
+ * @param inputService - momoi-keybindのInputServiceインスタンス。nullならno-op
+ * @param contextKey - コンテキストキー名。デフォルト: 'explorerFocus'
+ */
+declare function useExplorerFocus(inputService: InputServiceLike | null, contextKey?: string): {
+    onFocus: () => void;
+    onBlur: () => void;
+    tabIndex: number;
+};
+
+export { type ContextMenuState, type InputServiceLike, TreeContext, type TreeContextValue, TreeProvider, type TreeProviderProps, type UseContextMenuResult, type UseFileTreeResult, type UseTreeNodeResult, useContextMenu, useExplorerFocus, useExplorerKeybindings, useFileTree, useTreeContext, useTreeNode };