@alpaca-editor/core 1.0.4172 → 1.0.4174

package/src/editor/ui/PerfectTree.tsx

@@ -88,6 +88,10 @@ export interface TreeProps<T = any> {
   disableAutoSelectOnExpand?: boolean;
   /** Noun used in multi-select drag preview (e.g., "items", "components"). Default: "items" */
   multiDragNoun?: string;
+  /** Whether to enable keyboard navigation (default: true) */
+  enableKeyboardNavigation?: boolean;
+  /** Called when keyboard navigation focus changes */
+  onKeyboardNavigationChange?: (key: string) => void;
 }
 
 /**
@@ -346,6 +350,38 @@ const filterTreeNodes = (
     .filter((node): node is TreeNode<any> => node !== null);
 };
 
+// Helper types for keyboard navigation
+interface FlattenedNode<T = any> {
+  node: TreeNode<T>;
+  parent: TreeNode<T> | null;
+  depth: number;
+}
+
+// Helper function to flatten tree nodes into a depth-first list of visible nodes
+const flattenVisibleNodes = <T,>(
+  nodes: TreeNode<T>[],
+  expandedKeys: string[],
+  parent: TreeNode<T> | null = null,
+  depth: number = 0,
+): FlattenedNode<T>[] => {
+  const result: FlattenedNode<T>[] = [];
+
+  for (const node of nodes) {
+    // Add current node
+    result.push({ node, parent, depth });
+
+    // If expanded and has children, recursively add children
+    const isExpanded = expandedKeys.includes(node.key);
+    if (isExpanded && node.children && Array.isArray(node.children)) {
+      result.push(
+        ...flattenVisibleNodes(node.children, expandedKeys, node, depth + 1),
+      );
+    }
+  }
+
+  return result;
+};
+
 // NodeContent component extracted and memoized
 const NodeContent = memo(
   ({
@@ -580,9 +616,14 @@ export const PerfectTree = <T,>({
   searchClearDelay = 1500,
   disableAutoSelectOnExpand = false,
   multiDragNoun = "items",
+  enableKeyboardNavigation = true,
+  onKeyboardNavigationChange,
 }: TreeProps<T>) => {
   const [searchTerm, setSearchTerm] = useState("");
   const [isFocused, setIsFocused] = useState(false);
+  const [keyboardNavPosition, setKeyboardNavPosition] = useState<string | null>(
+    null,
+  );
   const searchTimeoutRef = useRef<NodeJS.Timeout | null>(null);
 
   // When toggling a node, notify parent and trigger external lazy load if needed.
@@ -686,47 +727,6 @@ export const PerfectTree = <T,>({
     };
   }, [onDragEnd]);
 
-  const handleDragEnd = useCallback(
-    (event: React.DragEvent<HTMLDivElement> | null) => {
-      isDraggingRef.current = false;
-      // Clear timeout when drag ends normally
-      if (dragTimeoutRef.current !== undefined) {
-        clearTimeout(dragTimeoutRef.current!);
-        dragTimeoutRef.current = undefined;
-      }
-      if (onDragEnd) {
-        onDragEnd(event);
-      }
-    },
-    [onDragEnd],
-  );
-
-  // Wrapper for onStartDrag that has access to the refs
-  const handleStartDragWithTimeout = useCallback(
-    (data: {
-      node: TreeNode<T>;
-      event: React.DragEvent<any>;
-      isMultiSelect: boolean;
-    }) => {
-      // Set the dragging ref to true when drag starts
-      isDraggingRef.current = true;
-
-      // Set up a timeout to auto-reset drag state if it gets stuck
-      dragTimeoutRef.current = setTimeout(() => {
-        if (isDraggingRef.current && onDragEnd) {
-          onDragEnd(null);
-          isDraggingRef.current = false;
-        }
-      }, 30000); // 30 second timeout
-
-      // Call the original onStartDrag
-      if (onStartDrag) {
-        onStartDrag(data);
-      }
-    },
-    [onStartDrag, onDragEnd],
-  );
-
   // Scroll to selected node when scrollToSelected is enabled and selectedKeys change
   const treeRef = useRef<HTMLDivElement>(null);
 
@@ -864,6 +864,46 @@ export const PerfectTree = <T,>({
     return filterTreeNodes(nodes, searchTerm, expandedKeys);
   }, [nodes, searchTerm, expandedKeys]);
 
+  // Wrapper for onStartDrag that has access to the refs
+  const handleStartDragWithTimeout = useCallback(
+    (data: {
+      node: TreeNode<T>;
+      event: React.DragEvent<any>;
+      isMultiSelect: boolean;
+    }) => {
+      // Mark dragging as active
+      isDraggingRef.current = true;
+      // Failsafe timeout to recover if the browser fails to emit dragend
+      dragTimeoutRef.current = setTimeout(() => {
+        if (isDraggingRef.current && onDragEnd) {
+          onDragEnd(null);
+          isDraggingRef.current = false;
+        }
+      }, 30000); // 30s safety timeout
+
+      // Delegate to consumer
+      if (onStartDrag) {
+        onStartDrag(data);
+      }
+    },
+    [onStartDrag, onDragEnd],
+  );
+
+  const handleDragEnd = useCallback(
+    (event: React.DragEvent<HTMLDivElement> | null) => {
+      isDraggingRef.current = false;
+      // Clear timeout when drag ends normally
+      if (dragTimeoutRef.current !== undefined) {
+        clearTimeout(dragTimeoutRef.current!);
+        dragTimeoutRef.current = undefined;
+      }
+      if (onDragEnd) {
+        onDragEnd(event);
+      }
+    },
+    [onDragEnd],
+  );
+
   // Recursive function to render tree nodes along with drop zones.
   const renderTreeList = useCallback(
     (
@@ -964,6 +1004,300 @@ export const PerfectTree = <T,>({
     [filteredNodes, renderTreeList],
   );
 
+  // Initialize keyboard navigation position when tree gains focus
+  useEffect(() => {
+    if (isFocused && !keyboardNavPosition) {
+      // Set initial position to first selected node, or first node
+      if (selectedKeys.length > 0 && selectedKeys[0]) {
+        setKeyboardNavPosition(selectedKeys[0]);
+      } else if (filteredNodes.length > 0 && filteredNodes[0]) {
+        setKeyboardNavPosition(filteredNodes[0].key);
+      }
+    }
+  }, [isFocused, keyboardNavPosition, selectedKeys, filteredNodes]);
+
+  // Update keyboard navigation position when selection changes externally (e.g., via click)
+  useEffect(() => {
+    if (isFocused && selectedKeys.length > 0 && selectedKeys[0]) {
+      // Only update if the current nav position is not in the selected keys
+      // This preserves nav position during shift-select
+      if (!keyboardNavPosition || !selectedKeys.includes(keyboardNavPosition)) {
+        setKeyboardNavPosition(selectedKeys[0]);
+      }
+    }
+  }, [selectedKeys, isFocused, keyboardNavPosition]);
+
+  // Helper function to scroll a node into view
+  const scrollNodeIntoView = useCallback((nodeKey: string) => {
+    if (!treeRef.current) return;
+
+    setTimeout(() => {
+      const treeContainer = treeRef.current;
+      if (!treeContainer) return;
+
+      const targetNode = treeContainer.querySelector(
+        `[data-node-key="${CSS.escape(nodeKey)}"]`,
+      ) as HTMLElement;
+
+      if (targetNode) {
+        let scrollContainer = targetNode.closest(
+          ".overflow-auto",
+        ) as HTMLElement;
+
+        if (!scrollContainer) {
+          scrollContainer = targetNode.closest(
+            '[style*="overflow"]',
+          ) as HTMLElement;
+        }
+
+        if (!scrollContainer) {
+          scrollContainer = treeContainer.parentElement as HTMLElement;
+        }
+
+        if (scrollContainer) {
+          const containerRect = scrollContainer.getBoundingClientRect();
+          const nodeRect = targetNode.getBoundingClientRect();
+
+          const isVisible =
+            nodeRect.top >= containerRect.top &&
+            nodeRect.bottom <= containerRect.bottom;
+
+          if (!isVisible) {
+            const scrollTop = scrollContainer.scrollTop;
+            const containerTop = containerRect.top;
+            const nodeTop = nodeRect.top;
+            const offset = nodeTop - containerTop;
+
+            const newScrollTop =
+              scrollTop +
+              offset -
+              containerRect.height / 2 +
+              nodeRect.height / 2;
+
+            scrollContainer.scrollTo({
+              top: newScrollTop,
+              behavior: "smooth",
+            });
+          }
+        } else {
+          targetNode.scrollIntoView({
+            behavior: "smooth",
+            block: "nearest",
+          });
+        }
+      }
+    }, 0);
+  }, []);
+
+  // Keyboard navigation functionality
+  useEffect(() => {
+    if (!enableKeyboardNavigation || !isFocused) return;
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      // Ignore if user is typing in an input, textarea, or contenteditable element
+      const target = event.target as HTMLElement;
+      if (
+        target.tagName === "INPUT" ||
+        target.tagName === "TEXTAREA" ||
+        target.contentEditable === "true" ||
+        target.isContentEditable
+      ) {
+        return;
+      }
+
+      // Get flattened list of visible nodes
+      const visibleNodes = flattenVisibleNodes(filteredNodes, expandedKeys);
+      if (visibleNodes.length === 0) return;
+
+      // Use keyboard navigation position as the current position
+      const currentIndex = keyboardNavPosition
+        ? visibleNodes.findIndex((n) => n.node.key === keyboardNavPosition)
+        : -1;
+
+      let newSelectedKey: string | null = null;
+      let shouldUseShift = false;
+
+      switch (event.key) {
+        case "ArrowDown": {
+          event.preventDefault();
+          shouldUseShift = event.shiftKey;
+          if (currentIndex < visibleNodes.length - 1) {
+            const nextNode = visibleNodes[currentIndex + 1];
+            if (nextNode) {
+              newSelectedKey = nextNode.node.key;
+            }
+          } else if (
+            currentIndex === -1 &&
+            visibleNodes.length > 0 &&
+            visibleNodes[0]
+          ) {
+            // No selection, select first node
+            newSelectedKey = visibleNodes[0].node.key;
+          }
+          break;
+        }
+
+        case "ArrowUp": {
+          event.preventDefault();
+          shouldUseShift = event.shiftKey;
+          if (currentIndex > 0) {
+            const prevNode = visibleNodes[currentIndex - 1];
+            if (prevNode) {
+              newSelectedKey = prevNode.node.key;
+            }
+          } else if (
+            currentIndex === -1 &&
+            visibleNodes.length > 0 &&
+            visibleNodes[0]
+          ) {
+            // No selection, select first node
+            newSelectedKey = visibleNodes[0].node.key;
+          }
+          break;
+        }
+
+        case "ArrowRight": {
+          event.preventDefault();
+          const currentNode =
+            currentIndex >= 0 ? visibleNodes[currentIndex] : undefined;
+          if (currentNode) {
+            const node = currentNode.node;
+            const isExpanded = expandedKeys.includes(node.key);
+
+            if (node.hasChildren || node.children?.length) {
+              if (!isExpanded) {
+                // Expand the node
+                if (onToggleExpand) {
+                  onToggleExpand(node.key);
+                }
+                if (
+                  node.hasChildren &&
+                  node.children === undefined &&
+                  onLazyLoad
+                ) {
+                  onLazyLoad(node);
+                }
+              } else if (
+                node.children &&
+                node.children.length > 0 &&
+                node.children[0]
+              ) {
+                // Move to first child
+                newSelectedKey = node.children[0].key;
+              }
+            }
+          }
+          break;
+        }
+
+        case "ArrowLeft": {
+          event.preventDefault();
+          const currentNode =
+            currentIndex >= 0 ? visibleNodes[currentIndex] : undefined;
+          if (currentNode) {
+            const node = currentNode.node;
+            const isExpanded = expandedKeys.includes(node.key);
+
+            if (isExpanded && (node.hasChildren || node.children?.length)) {
+              // Collapse the node
+              if (onToggleExpand) {
+                onToggleExpand(node.key);
+              }
+            } else if (currentNode.parent) {
+              // Move to parent node
+              newSelectedKey = currentNode.parent.key;
+            }
+          }
+          break;
+        }
+
+        case "Enter": {
+          event.preventDefault();
+          if (keyboardNavPosition) {
+            // Toggle expand/collapse if it has children
+            const currentNode =
+              currentIndex >= 0 ? visibleNodes[currentIndex] : undefined;
+            if (currentNode) {
+              const node = currentNode.node;
+              if (node.hasChildren || node.children?.length) {
+                if (onToggleExpand) {
+                  onToggleExpand(node.key);
+                }
+                if (
+                  node.hasChildren &&
+                  node.children === undefined &&
+                  onLazyLoad
+                ) {
+                  onLazyLoad(node);
+                }
+              }
+            }
+          }
+          break;
+        }
+
+        case "Home": {
+          event.preventDefault();
+          if (visibleNodes.length > 0) {
+            const firstNode = visibleNodes[0];
+            if (firstNode) {
+              newSelectedKey = firstNode.node.key;
+            }
+          }
+          break;
+        }
+
+        case "End": {
+          event.preventDefault();
+          if (visibleNodes.length > 0) {
+            const lastNode = visibleNodes[visibleNodes.length - 1];
+            if (lastNode) {
+              newSelectedKey = lastNode.node.key;
+            }
+          }
+          break;
+        }
+      }
+
+      if (newSelectedKey && newSelectedKey !== keyboardNavPosition) {
+        // Update keyboard navigation position
+        setKeyboardNavPosition(newSelectedKey);
+
+        if (onSelect) {
+          // Create a synthetic mouse event with shiftKey set for range selection
+          const syntheticEvent = {
+            shiftKey: shouldUseShift,
+            ctrlKey: false,
+            metaKey: false,
+            button: 0,
+          } as React.MouseEvent;
+          onSelect(newSelectedKey, syntheticEvent);
+        }
+        scrollNodeIntoView(newSelectedKey);
+        if (onKeyboardNavigationChange) {
+          onKeyboardNavigationChange(newSelectedKey);
+        }
+      }
+    };
+
+    document.addEventListener("keydown", handleKeyDown);
+
+    return () => {
+      document.removeEventListener("keydown", handleKeyDown);
+    };
+  }, [
+    enableKeyboardNavigation,
+    isFocused,
+    keyboardNavPosition,
+    filteredNodes,
+    expandedKeys,
+    onToggleExpand,
+    onSelect,
+    onLazyLoad,
+    scrollNodeIntoView,
+    onKeyboardNavigationChange,
+  ]);
+
   // Keyboard search functionality
   useEffect(() => {
     if (!enableKeyboardSearch || !isFocused) return;
@@ -980,6 +1314,21 @@ export const PerfectTree = <T,>({
         return;
       }
 
+      // Ignore navigation keys for search
+      if (
+        [
+          "ArrowUp",
+          "ArrowDown",
+          "ArrowLeft",
+          "ArrowRight",
+          "Enter",
+          "Home",
+          "End",
+        ].includes(event.key)
+      ) {
+        return;
+      }
+
       // Handle different key types
       if (event.key === "Escape") {
         // Clear search on Escape
@@ -1039,6 +1388,7 @@ export const PerfectTree = <T,>({
       onBlur={() => {
         setIsFocused(false);
         setSearchTerm("");
+        setKeyboardNavPosition(null);
         if (searchTimeoutRef.current) {
           clearTimeout(searchTimeoutRef.current);
           searchTimeoutRef.current = null;
@@ -1073,7 +1423,8 @@ const arePropsEqual = <T,>(
     prevProps.searchClearDelay !== nextProps.searchClearDelay ||
     prevProps.disableAutoSelectOnExpand !==
       nextProps.disableAutoSelectOnExpand ||
-    prevProps.multiDragNoun !== nextProps.multiDragNoun
+    prevProps.multiDragNoun !== nextProps.multiDragNoun ||
+    prevProps.enableKeyboardNavigation !== nextProps.enableKeyboardNavigation
   ) {
     return false;
   }

package/src/editor/utils/keyboardNavigation.ts

@@ -23,6 +23,8 @@ export interface KeyboardNavigationDependencies {
     data?: any;
     event?: React.SyntheticEvent;
   }) => Promise<any>;
+  showQuickSwitcher?: (show: boolean) => void;
+  cycleQuickSwitcher?: (direction: "next" | "prev" | "up" | "down") => void;
 }
 
 export function useKeyboardNavigation(deps: KeyboardNavigationDependencies) {
@@ -36,6 +38,8 @@ export function useKeyboardNavigation(deps: KeyboardNavigationDependencies) {
     loadItem,
     showInfoToast,
     executeCommand,
+    showQuickSwitcher,
+    cycleQuickSwitcher,
   } = deps;
 
   const handleKeyDownDebounced = useDebouncedCallback(
@@ -169,6 +173,18 @@ export function useKeyboardNavigation(deps: KeyboardNavigationDependencies) {
       );
 
       if (command) {
+        // Check if user is typing in an input field
+        const target = event.target as HTMLElement;
+        const isTyping =
+          target instanceof HTMLInputElement ||
+          target instanceof HTMLTextAreaElement ||
+          target.isContentEditable;
+
+        // Don't execute commands when typing in text fields
+        // F2 works everywhere except when typing
+        // Delete also won't trigger when typing
+        if (isTyping) return;
+
         event.preventDefault();
         const contentEditorItem = editContextRef.current?.contentEditorItem;
         if (!contentEditorItem) return;
@@ -211,6 +227,80 @@ export function useKeyboardNavigation(deps: KeyboardNavigationDependencies) {
         return;
       }
 
+      // Check if quick switcher is currently visible
+      const isQuickSwitcherVisible = editContextRef.current
+        ? (editContextRef.current as any).isQuickSwitcherVisible
+        : false;
+
+      // Handle navigation keys when switcher is visible (check this FIRST)
+      if (isQuickSwitcherVisible && editContextRef.current) {
+        // Shift key acts as ArrowRight for easy one-handed navigation
+        if (event.key === "Shift" && event.ctrlKey) {
+          console.log(`[KeyNav] Shift pressed (Ctrl held) - moving right`);
+          event.preventDefault();
+          event.stopPropagation();
+          cycleQuickSwitcher?.("next");
+          return;
+        }
+
+        // Arrow keys for navigation
+        if (
+          event.key === "ArrowLeft" ||
+          event.key === "ArrowRight" ||
+          event.key === "ArrowUp" ||
+          event.key === "ArrowDown"
+        ) {
+          console.log(`[KeyNav] Arrow key navigation: ${event.key}`);
+          event.preventDefault();
+          event.stopPropagation();
+
+          let direction: "next" | "prev" | "up" | "down";
+          switch (event.key) {
+            case "ArrowLeft":
+              direction = "prev";
+              break;
+            case "ArrowRight":
+              direction = "next";
+              break;
+            case "ArrowUp":
+              direction = "up";
+              break;
+            case "ArrowDown":
+              direction = "down";
+              break;
+          }
+          cycleQuickSwitcher?.(direction);
+          return;
+        }
+
+        // Enter or Escape to close
+        if (event.key === "Enter" || event.key === "Escape") {
+          console.log(
+            `[KeyNav] ${event.key} pressed - closing switcher with selection: ${event.key === "Enter"}`,
+          );
+          event.preventDefault();
+          event.stopPropagation();
+          // showQuickSwitcher(false) will be handled by the Enter key handler in EditorShell
+          // For now, we just let the keyup handler in EditorShell handle it
+          return;
+        }
+      }
+
+      // Handle quick switcher trigger (Ctrl+Shift pressed together) - only if NOT already visible
+      if (
+        !isQuickSwitcherVisible &&
+        ((event.key === "Shift" && event.ctrlKey) ||
+          (event.key === "Control" && event.shiftKey)) &&
+        editContextRef.current &&
+        browseHistory.length > 1
+      ) {
+        console.log("[KeyNav] Quick switcher trigger: Ctrl+Shift");
+        event.preventDefault();
+        event.stopPropagation();
+        showQuickSwitcher?.(true);
+        return;
+      }
+
       const target = event.target as HTMLElement;
       const isTyping =
         target instanceof HTMLInputElement ||
@@ -230,7 +320,13 @@ export function useKeyboardNavigation(deps: KeyboardNavigationDependencies) {
       }
       handleKeyDownDebounced(event);
     },
-    [handleKeyDownDebounced, editContextRef],
+    [
+      handleKeyDownDebounced,
+      editContextRef,
+      showQuickSwitcher,
+      cycleQuickSwitcher,
+      browseHistory,
+    ],
   );
 
   return { handleKeyDown };

package/src/editor/views/SingleEditView.tsx

@@ -38,23 +38,37 @@ export function SingleEditView({
       item?.templateId?.toLowerCase() ===
       "fe5dd826-48c6-436d-b87a-7c4210c7413b";
 
-    if (isMediaFolder) {
-      return <MediaFolderEditView item={item} />;
+    // Check if this is the media library root item (typically has template ID eb22c1a2-8899-4d2d-b36c-4aeb209e66b7)
+    const isMediaLibraryRoot =
+      item?.id?.toLowerCase() === "3d6658d8-a0bf-4e75-b3e2-d050fabcf4e1";
+
+    if (isMediaFolder || isMediaLibraryRoot) {
+      return (
+        <div data-view="media-folder-edit-view" className="h-full w-full">
+          <MediaFolderEditView item={item} />
+        </div>
+      );
     }
 
-    return <ItemEditor item={item} />;
+    return (
+      <div data-view="item-editor-view" className="h-full w-full">
+        <ItemEditor item={item} />
+      </div>
+    );
   }
 
   return (
-    <PageViewer
-      pageViewContext={pageViewContext}
-      showFormEditor={
-        editContext?.viewName == "page-editor" || !editContext?.isMobile
-      }
-      compareView={compareView}
-      name={name}
-      followEditsDefault={false}
-      className={className}
-    />
+    <div data-view="single-edit-view" className="h-full w-full">
+      <PageViewer
+        pageViewContext={pageViewContext}
+        showFormEditor={
+          editContext?.viewName == "page-editor" || !editContext?.isMobile
+        }
+        compareView={compareView}
+        name={name}
+        followEditsDefault={false}
+        className={className}
+      />
+    </div>
   );
 }

package/src/revision.ts

@@ -1,2 +1,2 @@
-export const version = "1.0.4172";
-export const buildDate = "2025-10-17 14:01:33";
+export const version = "1.0.4174";
+export const buildDate = "2025-10-21 01:59:37";