TidGi-Desktop/docs/internal/PromptTreeNavigation.md

Prompt Tree Navigation to Form Editor

Overview

Click on any prompt item in the tree view and automatically open the corresponding form editor with the correct tab and expanded state.

Implementation Details

1. Source Path Tracking

When plugins inject content into the prompt tree using injectToolList() or injectContent(), the system automatically adds a source field to track the original configuration location.

File: src/services/agentInstance/tools/defineTool.ts

// Build source path pointing to the plugin configuration
const pluginIndex = context.pluginIndex;
const source = pluginIndex !== undefined ? ['plugins', toolConfig.id] : undefined;

const toolPrompt: IPrompt = {
  id: `${toolId}-tool-list-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
  text: toolContent,
  caption: options.caption ?? `${definition.displayName} Tools`,
  enabled: true,
  source, // ['plugins', 'plugin-id']
};

The source array format: ['plugins', pluginId] or ['prompts', promptId, ...]

2. Navigation Trigger

File: src/pages/ChatTabContent/components/PromptTree.tsx

When a user clicks a tree node:

const handleNodeClick = useCallback((event: React.MouseEvent) => {
  event.stopPropagation();
  
  // Use source path if available, otherwise construct from fieldPath
  const targetFieldPath = (node.source && node.source.length > 0) 
    ? node.source 
    : [...fieldPath, node.id];
  
  setFormFieldsToScrollTo(targetFieldPath);
}, [node.source, node.id, fieldPath, setFormFieldsToScrollTo]);

3. Tab Switching

File: src/pages/ChatTabContent/components/PromptPreviewDialog/PromptConfigForm/templates/RootObjectFieldTemplate.tsx

The root form template listens to the navigation path and switches to the appropriate tab:

useEffect(() => {
  if (formFieldsToScrollTo.length > 0) {
    const targetTab = formFieldsToScrollTo[0]; // 'prompts', 'plugins', or 'response'
    const tabIndex = properties.findIndex(property => property.name === targetTab);
    if (tabIndex !== -1 && tabIndex !== activeTab) {
      setActiveTab(tabIndex);
    }
  }
}, [formFieldsToScrollTo, properties, activeTab]);

4. Item Expansion

File: src/pages/ChatTabContent/components/PromptPreviewDialog/EditView.tsx

The EditView component handles the expansion of nested items:

useEffect(() => {
  if (formFieldsToScrollTo.length > 0 && editorMode === 'form') {
    const savedPath = [...formFieldsToScrollTo];
    
    // Wait for RootObjectFieldTemplate to switch tabs
    setTimeout(() => {
      setFormFieldsToScrollTo([]); // Clear after tab switches
      
      // Step 1: Expand top-level item
      const topLevelKey = savedPath[0];
      const firstItemId = savedPath[1];
      expandItemsByPath(topLevelKey, [firstItemId]);
      
      // Step 2: Expand nested children if present
      if (savedPath.length > 2) {
        setTimeout(() => {
          const parentIndex = findParentIndex(topLevelKey, firstItemId);
          const nestedFieldPath = `${topLevelKey}_${parentIndex}_children`;
          const nestedItemIds = savedPath.slice(2);
          expandItemsByPath(nestedFieldPath, nestedItemIds);
        }, 300);
      }
    }, 100);
  }
}, [formFieldsToScrollTo, editorMode, agentFrameworkConfig]);

5. Store Management

File: src/pages/Agent/store/agentChatStore/PromptPreviewStore.ts

The store maintains:

• Expansion state for all array fields
• Navigation path queue
• Helper functions to expand/collapse items

interface PromptPreviewStore {
  arrayExpansionStore: Record<string, Record<number, boolean>>;
  formFieldsToScrollTo: string[];
  
  setItemExpanded: (fieldPath: string, index: number, expanded: boolean) => void;
  setFormFieldsToScrollTo: (path: string[]) => void;
}

Data Flow

1. User clicks "Git Tools" in tree view
2. PromptTree reads node.source → ['plugins', 'g3f4e5d6-7e8f-9g0h-1i2j-l3m4n5o6p7q8']
3. Calls setFormFieldsToScrollTo(['plugins', 'g3f4e5d6-7e8f-9g0h-1i2j-l3m4n5o6p7q8'])
4. RootObjectFieldTemplate detects path[0] = 'plugins' → switches to plugins tab
5. EditView expands the plugin item with id 'g3f4e5d6-7e8f-9g0h-1i2j-l3m4n5o6p7q8'
6. Form scrolls to and highlights the target element

Timing Considerations

The implementation uses careful timing to ensure proper rendering:

• 100ms delay: Wait for tab switch before expanding items
• 300ms delay: Wait for parent expansion before expanding nested children
• 500ms delay: Wait for all expansions before scrolling to target

These delays account for React's rendering cycles and DOM updates.

Extension Points

To add navigation support for custom components:

1. Add source field when creating prompts
2. Ensure source points to the configuration location: ['topLevelKey', 'itemId', ...]
3. The navigation system will automatically handle the rest

Related Files

• src/services/agentInstance/tools/defineTool.ts - Source path injection
• src/services/agentInstance/tools/types.ts - Context types with pluginIndex
• src/services/agentInstance/promptConcat/promptConcat.ts - Plugin index passing
• src/pages/ChatTabContent/components/PromptTree.tsx - Click handler
• src/pages/ChatTabContent/components/PromptPreviewDialog/EditView.tsx - Expansion logic
• src/pages/ChatTabContent/components/PromptPreviewDialog/PromptConfigForm/templates/RootObjectFieldTemplate.tsx - Tab switching
• src/pages/Agent/store/agentChatStore/PromptPreviewStore.ts - State management