[FEATURE] Advanced Node Hierarchy Indentation System

Overview

Implement sophisticated node hierarchy indentation rules with intelligent child transfer logic, node type compatibility checking, and collapsed state awareness. This system builds on the current basic Tab/Shift+Tab functionality to provide predictable, IDE-quality hierarchy management.

Background & Context

The current implementation provides basic indentation (Tab/Shift+Tab) and visual collapse/expand controls. This enhancement adds the advanced hierarchy rules from NodeSpace core-ui analysis, enabling sophisticated knowledge management workflows with predictable node organization behavior.

Current State

• ✅ Visual System: Chevron controls with hover behavior and smooth animations
• ✅ Basic Indentation: Tab (indent) and Shift+Tab (outdent) with cursor preservation
• ✅ Collapse/Expand: Visual state management with children visibility control
• ❌ Node Compatibility: No canHaveChildren property or type-based rules
• ❌ Child Transfer: No intelligent child movement during hierarchy operations
• ❌ Collapsed Awareness: Hierarchy operations don't consider collapsed state

Self-Contained Scope

• canHaveChildren Property: Add boolean property to MinimalBaseNode following Svelte patterns
• Enhanced Indentation Rules: Implement sophisticated Tab/Shift+Tab logic with validation
• Child Transfer System: Intelligent child node movement with depth preservation
• Collapsed State Integration: Hierarchy operations aware of visual state
• Node Type Compatibility: Prevent invalid parent-child relationships
• Comprehensive Testing: Unit tests + integration tests with hierarchy scenarios
• Documentation: Usage examples and behavior specifications

Implementation Approach

1. Node Type Compatibility System

Add canHaveChildren property to control node parenting rules:

// MinimalBaseNode.svelte enhancement
export let canHaveChildren: boolean = true; // Svelte property pattern

// Node-specific overrides in component usage:
// <MinimalBaseNode canHaveChildren={nodeType !== 'ai-chat'} ... />

2. Enhanced Indentation Logic

Implement sophisticated Tab/Shift+Tab rules:

// Enhanced indent validation
function canIndent(node: NodeData, siblings: NodeData[]): boolean {
  const nodeIndex = siblings.findIndex(s => s.id === node.id);
  if (nodeIndex <= 0) return false; // No previous sibling
  
  const previousSibling = siblings[nodeIndex - 1];
  return previousSibling.canHaveChildren; // Type compatibility check
}

// Outdent with sibling transfer
function outdentNode(node: NodeData): void {
  // Move node up one level
  // Next immediate sibling becomes child of outdented node
  // Preserves hierarchy relationships
}

3. Child Transfer System

Implement depth-aware child movement logic:

interface ChildTransferConfig {
  sourceNode: NodeData;
  targetNode: NodeData;
  collapsedNodes: Set<string>;
  sourceDepth: number;
}

function transferChildrenWithDepthPreservation(config: ChildTransferConfig): void {
  // Root node deletion: children → target root ancestor
  // Non-root deletion: children → target node directly
  // Collapsed target: insert children at beginning + auto-expand
  // Expanded target: insert children at end
}

4. Enter Key Enhancement

Enhance content splitting behavior:

function handleEnterWithChildren(node: NodeData, isCollapsed: boolean): void {
  if (isCollapsed) {
    // Children stay with original (left) node
    return splitContent(node, { preserveChildren: true });
  } else {
    // Children move to new (right) node  
    return splitContent(node, { transferChildren: true });
  }
}

Technical Specifications

Reference Files

• MinimalBaseNode.svelte: /nodespace-app/src/lib/design/components/MinimalBaseNode.svelte - Add canHaveChildren property
• BaseNodeViewer.svelte: /nodespace-app/src/lib/design/components/BaseNodeViewer.svelte - Enhanced keyboard handlers
• TextNode.svelte: /nodespace-app/src/lib/components/TextNode.svelte - Integration point for text-specific rules
• Previous Implementation: /Users/malibio/nodespace/nodespace-core-ui/src/utils/textKeyboardHandler.ts - Reference for transfer logic

Integration Points

• Existing Collapse System: Leverage current expanded property and chevron controls
• Keyboard Handlers: Enhance existing handleIndentNode and handleOutdentNode functions
• Visual Feedback: Maintain current chevron positioning and animation system
• State Management: Integrate with current nodes state management in BaseNodeViewer

Design System Integration

• Follow Existing Patterns: Use same prop patterns as allowNewNodeOnEnter, multiline, etc.
• Maintain Visual Consistency: Preserve current chevron positioning and color coordination
• Component Architecture: Follow established parent-child communication patterns

Acceptance Criteria

Core Functionality

• canHaveChildren Property: MinimalBaseNode accepts boolean property with default true
• Node Type Compatibility: Cannot indent when previous sibling has canHaveChildren=false
• Enhanced Indent Rules: Tab indentation respects node type compatibility
• Enhanced Outdent Rules: Shift+Tab moves next sibling as child of outdented node
• Child Transfer Logic: Backspace/Delete intelligently transfers children based on depth
• Collapsed State Awareness: Children insert at beginning for collapsed targets, end for expanded
• Auto-Expansion: Nodes receiving children automatically expand to show new content

Behavioral Requirements

• Predictable Hierarchy: Operations follow clear, documented rules without surprises
• Cursor Preservation: All operations maintain cursor position as currently implemented
• Visual Feedback: Operations provide immediate visual confirmation of hierarchy changes
• Undo Compatibility: All operations integrate with existing undo/redo systems
• Performance: Operations complete in <50ms for trees up to 1000 nodes

Integration Requirements

• Current System Compatibility: Existing collapse/expand functionality unaffected
• Component Integration: Works seamlessly with existing BaseNodeViewer/MinimalBaseNode architecture
• Type Safety: Full TypeScript support with proper interfaces and type checking
• State Management: Integrates with current reactive state patterns
• Event Handling: Follows existing event dispatcher patterns for hierarchy changes

Test Scenarios

Node Type Compatibility Tests

// Test cannot indent into ai-chat node
const aiChatNode = { type: 'ai-chat', canHaveChildren: false };
const textNode = { type: 'text', canHaveChildren: true };
expect(canIndent(textNode, [aiChatNode, textNode])).toBe(false);

// Test can indent into text node
expect(canIndent(textNode, [textNode, textNode])).toBe(true);

Outdent with Sibling Transfer Tests

// Before: Parent → [NodeA, NodeB, NodeC]
// Outdent NodeA
// After: [NodeA → [NodeB], Parent → [NodeC]]

Child Transfer Scenarios

// Root node deletion: children → target root ancestor
// Non-root deletion: children → target directly
// Collapsed target: children inserted at beginning + auto-expand
// Expanded target: children appended at end

Enter Key with Children Tests

// Collapsed parent + Enter: children stay with left node
// Expanded parent + Enter: children move to right node

Resources & References

Implementation References

• Previous NodeSpace Implementation: /Users/malibio/nodespace/nodespace-core-ui/src/utils/textKeyboardHandler.ts - Complete reference implementation
• Current Basic Implementation: BaseNodeViewer.svelte lines 237-413 - Current indent/outdent handlers
• Node Utils Reference: /Users/malibio/nodespace/nodespace-core-ui/src/utils/nodeUtils.ts - indentNode, outdentNode functions

Architecture Documentation

• Node Hierarchy System: /docs/architecture/components/ui-ux-system.md#node-hierarchy-interaction-system - Complete system overview
• Component Patterns: /docs/architecture/components/node-inheritance.md - Base component architecture
• Keyboard Handlers: Current implementation patterns in BaseNodeViewer

Design System Integration

• Component Props: Follow existing MinimalBaseNode prop patterns (allowNewNodeOnEnter, multiline, etc.)
• Color System: Use existing node type colors from design system
• Animation System: Leverage current chevron rotation and transition system

Implementation Guidance

Phase 1: Property Foundation

1. Add canHaveChildren: boolean = true to MinimalBaseNode props
2. Update component usage to pass node-type-specific values
3. Create validation functions for indent operations

Phase 2: Enhanced Rules

1. Implement sophisticated indent/outdent validation
2. Add sibling transfer logic for outdent operations
3. Enhance Enter key behavior with children consideration

Phase 3: Child Transfer System

1. Implement depth-aware child transfer algorithm
2. Add collapsed state awareness to transfer logic
3. Implement auto-expansion for nodes receiving children

Phase 4: Integration & Testing

1. Integrate with existing collapse/expand system
2. Add comprehensive test coverage for all scenarios
3. Performance testing with large hierarchies
4. Accessibility testing for keyboard navigation

Definition of Done

• Feature works end-to-end: All indentation rules functional with visual feedback
• Comprehensive testing: >90% test coverage including edge cases and integration tests
• Performance validated: Operations complete within performance targets
• Documentation complete: Updated architecture docs and usage examples
• Type safety: Full TypeScript integration with proper interfaces
• Accessibility verified: Keyboard navigation and screen reader compatibility
• Visual consistency: Maintains current design system integration
• Code review passed: Senior architect review completed
• Integration verified: Works seamlessly with existing collapse/expand system
• Ready for production: No breaking changes to existing functionality

This implementation will provide sophisticated, predictable hierarchy management that matches modern IDE experiences while building on NodeSpace's existing visual and interaction foundation.