ftreeview 0.1.1

package/src/hooks/useNavigation.js

@@ -0,0 +1,247 @@
+/**
+ * useNavigation - Navigation Hook for ftree
+ *
+ * Handles keyboard navigation, cursor management, and viewport control
+ * for the file tree view. Provides vim-style keybindings and auto-scrolling.
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+import { useInput, useApp } from 'ink';
+
+/**
+ * Configuration constants for navigation behavior
+ */
+const VIEWPORT_MARGIN = 3; // Keep cursor 3 lines from viewport edges
+
+/**
+ * React hook for managing navigation state and keyboard input
+ *
+ * @param {FileNode[]} flatList - Flattened list of visible nodes from useTree
+ * @param {Function} rebuildTree - Callback to rebuild tree with modified nodes
+ * @param {Function|null} refreshFlatList - Callback to refresh visible list without full rebuild
+ * @returns {{cursor: number, viewportStart: number, exit: Function, setCursorByPath: Function, setCursor: Function}} Navigation state
+ */
+export function useNavigation(flatList = [], rebuildTree, refreshFlatList = null) {
+  const { exit } = useApp();
+
+  // Calculate viewport height (terminal height minus header and status bar)
+  const viewportHeight = process.stdout.rows - 2;
+
+  // Navigation state
+  const [cursor, setCursor] = useState(0);
+  const [viewportStart, setViewportStart] = useState(0);
+
+  const refreshVisibleTree = useCallback(() => {
+    if (typeof refreshFlatList === 'function') {
+      refreshFlatList();
+      return;
+    }
+    rebuildTree(true);
+  }, [refreshFlatList, rebuildTree]);
+
+  /**
+   * Set cursor position by looking up a path in the flat list
+   * Useful for preserving cursor position across rebuilds
+   *
+   * @param {string} path - The path to find in the flat list
+   * @returns {number} The new cursor position, or -1 if not found
+   */
+  const setCursorByPath = useCallback((path) => {
+    if (!path || flatList.length === 0) return -1;
+
+    // Find the node with matching path
+    const newIndex = flatList.findIndex((node) => node.path === path);
+
+    if (newIndex !== -1) {
+      setCursor(newIndex);
+      return newIndex;
+    }
+
+    return -1;
+  }, [flatList]);
+
+  /**
+   * Find the parent of the current node in the flat list
+   * Used by smartCollapse to jump to parent when already collapsed
+   *
+   * @param {number} currentIndex - Current cursor position
+   * @returns {number|null} Index of parent node or null
+   */
+  const findParentIndex = useCallback((currentIndex) => {
+    if (currentIndex <= 0) return null;
+
+    const currentDepth = flatList[currentIndex]?.depth ?? 0;
+
+    // Search backwards for a node with shallower depth
+    for (let i = currentIndex - 1; i >= 0; i--) {
+      if (flatList[i]?.depth < currentDepth) {
+        return i;
+      }
+    }
+
+    return null;
+  }, [flatList]);
+
+  /**
+   * Move cursor up one line
+   */
+  const moveUp = useCallback(() => {
+    setCursor((prev) => Math.max(0, prev - 1));
+  }, []);
+
+  /**
+   * Move cursor down one line
+   */
+  const moveDown = useCallback(() => {
+    setCursor((prev) => Math.min(flatList.length - 1, prev + 1));
+  }, [flatList.length]);
+
+  /**
+   * Expand the directory at current cursor position
+   * Only works on directories, refreshes visible nodes
+   */
+  const expand = useCallback(() => {
+    if (flatList.length === 0) return;
+
+    const node = flatList[cursor];
+    if (!node) return;
+
+    // Only directories can be expanded
+    if (node.isDir && !node.expanded) {
+      node.expanded = true;
+      refreshVisibleTree();
+    }
+  }, [cursor, flatList, refreshVisibleTree]);
+
+  /**
+   * Smart collapse: collapse if expanded, jump to parent if collapsed
+   */
+  const smartCollapse = useCallback(() => {
+    if (flatList.length === 0) return;
+
+    const node = flatList[cursor];
+    if (!node) return;
+
+    if (node.expanded && node.isDir) {
+      // Collapse the current directory
+      node.expanded = false;
+      refreshVisibleTree();
+    } else {
+      // Jump to parent directory
+      const parentIndex = findParentIndex(cursor);
+      if (parentIndex !== null) {
+        setCursor(parentIndex);
+      }
+    }
+  }, [cursor, flatList, refreshVisibleTree, findParentIndex]);
+
+  /**
+   * Toggle expanded state of current directory
+   */
+  const toggle = useCallback(() => {
+    if (flatList.length === 0) return;
+
+    const node = flatList[cursor];
+    if (!node || !node.isDir) return;
+
+    node.expanded = !node.expanded;
+    refreshVisibleTree();
+  }, [cursor, flatList, refreshVisibleTree]);
+
+  /**
+   * Jump to the first item in the list
+   */
+  const jumpToTop = useCallback(() => {
+    setCursor(0);
+  }, []);
+
+  /**
+   * Jump to the last item in the list
+   */
+  const jumpToBottom = useCallback(() => {
+    setCursor(Math.max(0, flatList.length - 1));
+  }, [flatList.length]);
+
+  /**
+   * Refresh the tree by rebuilding it
+   */
+  const refresh = useCallback(() => {
+    rebuildTree(true);
+  }, [rebuildTree]);
+
+  /**
+   * Handle keyboard input using Ink's useInput hook
+   */
+  useInput((input, key) => {
+    // Vim-style and arrow key navigation
+    if (key.upArrow || input === 'k') {
+      moveUp();
+    } else if (key.downArrow || input === 'j') {
+      moveDown();
+    } else if (key.rightArrow || input === 'l' || key.return) {
+      expand();
+    } else if (key.leftArrow || input === 'h') {
+      smartCollapse();
+    } else if (key.ctrl && input === 'c') {
+      exit();
+    } else if (input === 'q') {
+      exit();
+    } else if (input === ' ') {
+      toggle();
+    } else if (input === 'g') {
+      jumpToTop();
+    } else if (input === 'G') {
+      jumpToBottom();
+    } else if (input === 'r') {
+      refresh();
+    }
+  });
+
+  /**
+   * Auto-scroll viewport to keep cursor in view
+   * Adjust viewportStart when cursor moves near edges
+   */
+  useEffect(() => {
+    if (flatList.length === 0) {
+      setViewportStart(0);
+      return;
+    }
+
+    // Ensure cursor is visible
+    if (cursor < viewportStart) {
+      // Cursor is above viewport, scroll up
+      setViewportStart(cursor);
+    } else if (cursor >= viewportStart + viewportHeight) {
+      // Cursor is below viewport, scroll down
+      setViewportStart(cursor - viewportHeight + 1);
+    }
+
+    // Keep cursor comfortably away from edges (margin)
+    if (cursor - viewportStart < VIEWPORT_MARGIN && viewportStart > 0) {
+      // Cursor is too close to top edge, scroll up
+      setViewportStart(Math.max(0, cursor - VIEWPORT_MARGIN));
+    } else if (viewportStart + viewportHeight - cursor < VIEWPORT_MARGIN) {
+      // Cursor is too close to bottom edge, scroll down
+      const maxStart = Math.max(0, flatList.length - viewportHeight);
+      setViewportStart(Math.min(maxStart, cursor - viewportHeight + VIEWPORT_MARGIN + 1));
+    }
+  }, [cursor, flatList.length, viewportHeight]);
+
+  // Reset cursor when flat list becomes empty
+  useEffect(() => {
+    if (flatList.length === 0) {
+      setCursor(0);
+      setViewportStart(0);
+    }
+  }, [flatList.length]);
+
+  return {
+    cursor,
+    viewportStart,
+    exit,
+    setCursorByPath,
+    setCursor,
+  };
+}
+
+export default useNavigation;