TachUI Navigation Plugin Structure

Comprehensive file-level documentation of packages/navigation/

This document provides a complete overview of TachUI's Navigation plugin structure, explaining the purpose and functionality of every file and directory in the packages/navigation/ codebase.

📋 Overview

Current Status: Production Ready - 16 TypeScript files, 7 test files, 228KB source

The @tachui/navigation plugin extends TachUI's core framework with comprehensive navigation capabilities including stack-based navigation, tab interfaces, and programmatic routing. It provides SwiftUI-compatible navigation patterns while maintaining excellent performance and accessibility.

Key Features:

NavigationView - SwiftUI-style stack-based navigation with push/pop operations
NavigationLink - Declarative navigation with automatic back button handling
TabView System - Complete tab interface with multiple implementations (Simple, Enhanced, Advanced)
Navigation Stack - Programmatic navigation with history management
Routing Integration - URL-based routing with browser history synchronization
Enhanced UX Features - Smooth animations, gesture navigation, and accessibility compliance

The Navigation plugin is organized into 8 main modules:

Core Navigation (navigation-view.ts, navigation-link.ts) - Basic navigation components
Tab System (tab-view.ts, enhanced-tab-view.ts, advanced-tab-view.ts) - Tabbed interface components
Navigation Management (navigation-manager.ts, navigation-stack.ts) - State and stack management
Routing System (navigation-router.ts, navigation-path.ts) - URL routing and path management
Enhanced Features (programmatic-navigation.ts, enhanced-navigation-hooks.ts) - Advanced navigation utilities
Modifier Integration (navigation-modifiers.ts) - Navigation-specific modifiers
Environment Integration (navigation-environment.ts) - Context and environment management
Type Definitions (types.ts) - Comprehensive TypeScript support

🎯 Root Level

packages/navigation/
├── package.json               # Navigation plugin package configuration
├── tsconfig.json             # TypeScript configuration for development
├── vite.config.ts            # Vite build configuration optimized for plugin
├── vitest.config.ts          # Test configuration for Navigation plugin
├── vitest.benchmark.config.ts # Performance benchmarking configuration
├── dist/                     # Compiled plugin output with tree-shaking support
├── src/                      # Source code for all Navigation functionality
├── __tests__/               # Comprehensive test suite with integration testing
└── benchmarks/              # Performance benchmarking and optimization

📝 Root File Details

`package.json`

Purpose: Navigation plugin package configuration and dependencies
Functionality:

Package name: @tachui/navigation as official TachUI plugin
Peer dependency on @tachui/core for framework integration
ESM/CJS dual output with TypeScript declarations
Tree-shakeable exports for optimal bundle sizes (~23KB total)

`vitest.benchmark.config.ts`

Purpose: Performance benchmarking configuration for navigation operations
Functionality:

Navigation performance benchmarking (push/pop operations, tab switching)
Memory usage analysis for navigation state management
Bundle size impact measurement and regression testing
Real-world navigation scenario performance testing

🧭 Core Navigation (`navigation-view.ts`, `navigation-link.ts`)

SwiftUI-style stack-based navigation with declarative routing

`navigation-view.ts`

Purpose: SwiftUI NavigationView implementation with stack-based navigation
Functionality:

Navigation Stack Management: Push/pop operations with automatic back button handling
View Transition Animations: Smooth slide transitions with configurable timing
Navigation Bar: Automatic navigation bar with title, back button, and custom actions
History Integration: Browser history synchronization with navigation stack
Gesture Navigation: Swipe-back gesture support for mobile devices
Accessibility: Screen reader navigation announcements and focus management

`navigation-link.ts`

Purpose: Declarative navigation triggers with SwiftUI-compatible API
Functionality:

Declarative Navigation: NavigationLink component for seamless view transitions
Automatic Back Button: Automatic back button handling with navigation stack
Custom Triggers: Support for custom navigation triggers and actions
State Preservation: View state preservation during navigation
Accessibility: ARIA navigation landmarks and keyboard accessibility
Performance: Lazy view loading for efficient memory usage

📑 Tab System (`tab-view.ts`, `enhanced-tab-view.ts`, `advanced-tab-view.ts`)

Complete tabbed interface system with multiple implementation options

📝 Tab System Details

`simple-tab-view.ts`

Purpose: Lightweight tab interface for basic tabbed navigation
Functionality:

Basic Tab Interface: Simple tab switching with minimal configuration
Tab State Management: Active tab tracking with reactive updates
Content Lazy Loading: Tab content loaded only when accessed
Keyboard Navigation: Arrow key navigation between tabs
Bundle Size: ~8KB - ideal for applications with basic tab needs

`enhanced-tab-view.ts`

Purpose: Enhanced tab interface with advanced features and customization
Functionality:

Advanced Tab Features: Tab reordering, closeable tabs, and custom tab rendering
Tab Bar Customization: Custom tab bar styling and positioning
Badge Support: Tab badges for notifications and status indicators
Overflow Handling: Tab overflow with horizontal scrolling
Animation System: Smooth tab switching animations with configurable effects
Bundle Size: ~15KB - comprehensive tab functionality

`advanced-tab-view.ts`

Purpose: Full-featured tab system with desktop-class functionality
Functionality:

Desktop-Class Features: Tab groups, tab nesting, and advanced tab management
Context Menus: Right-click context menus for tab operations
Tab Persistence: Tab state persistence across sessions
Multi-Window Support: Tab coordination across multiple windows
Advanced Gestures: Pinch-to-zoom, multi-touch tab gestures
Bundle Size: ~23KB - complete tab system for complex applications

🗃️ Navigation Management (`navigation-manager.ts`, `navigation-stack.ts`)

Centralized navigation state and stack management

`navigation-manager.ts`

Purpose: Centralized navigation state coordination and management
Functionality:

Global Navigation State: Centralized navigation state across the application
Route Registration: Route definition and matching with parameter extraction
Navigation History: Navigation history tracking with undo/redo capabilities
Deep Linking: URL deep linking with automatic navigation stack reconstruction
Navigation Guards: Route guards for authentication and authorization
Performance Monitoring: Navigation performance tracking and optimization

`navigation-stack.ts`

Purpose: Navigation stack implementation with efficient memory management
Functionality:

Stack Operations: Efficient push/pop/replace operations with state preservation
Memory Management: Automatic cleanup of unused navigation states
State Serialization: Navigation state serialization for persistence and debugging
Transition Management: View transition coordination and lifecycle management
Error Recovery: Navigation error recovery and fallback mechanisms
Performance Optimization: Optimized stack operations for smooth navigation

🔗 Routing System (`navigation-router.ts`, `navigation-path.ts`)

URL-based routing with browser history integration

📝 Routing System Details

`navigation-router.ts`

Purpose: URL routing system with browser history synchronization
Functionality:

URL Route Matching: Flexible route pattern matching with parameter extraction
History Management: Browser history API integration with navigation stack
Route Parameters: Dynamic route parameters with type validation
Query String Support: URL query string parsing and management
Hash Navigation: Hash-based navigation for single-page applications
SEO Integration: Meta tag updates for search engine optimization

`navigation-path.ts`

Purpose: Navigation path management and URL construction utilities
Functionality:

Path Construction: Type-safe path construction with parameter validation
Route Parsing: URL parsing and route parameter extraction
Path Normalization: URL normalization and canonical path generation
Base Path Support: Application base path configuration and handling
Path Validation: Route path validation and error handling
Performance: Efficient path matching with caching and optimization

⚡ Enhanced Features (`programmatic-navigation.ts`, `enhanced-navigation-hooks.ts`)

Advanced navigation utilities and programmatic control

📝 Enhanced Features Details

`programmatic-navigation.ts`

Purpose: Programmatic navigation API for complex navigation scenarios
Functionality:

Navigation API: Comprehensive programmatic navigation methods
Batch Operations: Batch navigation operations with transaction support
Animation Control: Fine-grained control over navigation animations
Navigation Conditions: Conditional navigation with validation and confirmation
Custom Transitions: Custom transition animations and effects
State Management: Advanced state management during programmatic navigation

`enhanced-navigation-hooks.ts`

Purpose: React-style hooks for navigation state and lifecycle management
Functionality:

Navigation Hooks: useNavigation, useNavigationState, useRouter hooks
Lifecycle Hooks: Navigation lifecycle event hooks (onEnter, onLeave, onUpdate)
State Hooks: Navigation state management hooks with reactive updates
Route Hooks: Route parameter and query string access hooks
History Hooks: Navigation history manipulation and tracking hooks
Performance Hooks: Navigation performance monitoring and optimization hooks

🎨 Modifier Integration (`navigation-modifiers.ts`)

Navigation-specific modifiers for enhanced styling and behavior

`navigation-modifiers.ts`

Purpose: Navigation-specific modifiers for enhanced navigation styling
Functionality:

Navigation Bar Modifiers: Navigation bar styling and customization modifiers
Tab Bar Modifiers: Tab bar appearance and behavior modifiers
Transition Modifiers: Navigation transition customization modifiers
Navigation Title Modifiers: Navigation title styling and behavior modifiers
Back Button Modifiers: Back button customization and styling modifiers
Integration: Seamless integration with TachUI's modifier system

Available Navigation Modifiers:

typescript

// Navigation bar styling
.navigationBarStyle(style: NavigationBarStyle)
.navigationTitle(title: string | Signal<string>)
.navigationBarHidden(hidden: boolean)

// Tab bar customization  
.tabBarStyle(style: TabBarStyle)
.tabItem(image: string, text: string)
.tabBarHidden(hidden: boolean)

// Navigation transitions
.navigationTransition(transition: NavigationTransition)
.transitionDuration(duration: number)
.transitionEasing(easing: string)

// Advanced navigation behavior
.navigationBackButtonHidden(hidden: boolean)
.navigationGesturesEnabled(enabled: boolean)
.navigationInteractivePopEnabled(enabled: boolean)

🌐 Environment Integration (`navigation-environment.ts`)

Navigation context and environment management

📝 Environment Integration Details

`navigation-environment.ts`

Purpose: Navigation environment context and dependency injection
Functionality:

Navigation Context: Navigation state context provider for component tree
Environment Objects: Navigation environment objects for global navigation state
Dependency Injection: Navigation service injection and management
Context Sharing: Navigation context sharing across component boundaries
State Synchronization: Navigation state synchronization across contexts
Performance: Efficient context updates with minimal re-rendering

🏷️ Type Definitions (`types.ts`)

Comprehensive TypeScript definitions for navigation system

📝 Type Definition Details

`types.ts`

Purpose: Complete TypeScript type definitions for navigation system
Functionality:

Core Types: Navigation component and state type definitions
Route Types: Route definition and parameter type definitions
Event Types: Navigation event and lifecycle type definitions
Configuration Types: Navigation configuration and option type definitions
Hook Types: Navigation hook and utility function type definitions
Generic Types: Generic type utilities for type-safe navigation

Key Type Definitions:

typescript

// Core navigation types
export interface NavigationViewProps extends ComponentProps {
  children: ComponentInstance | ComponentInstance[]
  navigationBarHidden?: boolean
  gesturesEnabled?: boolean
}

// Route definition types
export interface RouteDefinition {
  path: string
  component: ComponentFactory
  params?: RouteParams
  guards?: NavigationGuard[]
}

// Navigation state types
export interface NavigationState {
  currentRoute: string
  navigationStack: NavigationEntry[]
  tabState?: TabState
  isNavigating: boolean
}

// Tab system types
export interface TabViewProps extends ComponentProps {
  tabs: TabDefinition[]
  selectedTab?: number | Signal<number>
  tabBarStyle?: TabBarStyle
}

🧪 Comprehensive Testing (`tests/`)

Extensive test suite covering all navigation functionality

__tests__/
├── navigation-link.test.ts           # NavigationLink component testing
├── navigation-modifiers.test.ts      # Navigation modifier system testing
├── navigation-stack.test.ts          # Navigation stack functionality testing
├── simple-tab-view.test.ts          # Simple TabView component testing
├── enhanced-tab-view.test.ts         # Enhanced TabView functionality testing
├── advanced-tab-view.test.ts         # Advanced TabView features testing
└── navigation-hooks.test.ts          # Navigation hooks and utilities testing

📝 Test Coverage Details

`navigation-stack.test.ts`

Purpose: Navigation stack functionality and performance testing
Test Coverage:

Stack push/pop operations with state preservation
Memory management and cleanup during navigation
Navigation history tracking and undo/redo functionality
Error recovery and fallback mechanisms
Performance benchmarking for large navigation stacks

`enhanced-tab-view.test.ts`

Purpose: Enhanced TabView comprehensive functionality testing
Test Coverage:

Advanced tab features (reordering, closeable tabs, badges)
Tab overflow handling and horizontal scrolling
Keyboard navigation and accessibility compliance
Tab state persistence and recovery
Animation system performance and smoothness

📊 Performance Benchmarking (`benchmarks/`)

Performance analysis and optimization for navigation operations

benchmarks/
├── README.md                         # Benchmarking documentation and results
├── navigation-performance.bench.ts   # Core navigation performance benchmarking
├── bundle-size.bench.ts             # Bundle size impact analysis
├── quick.bench.ts                   # Quick performance regression testing
└── browser.spec.ts                  # Browser-based navigation performance testing

📝 Benchmark Details

`navigation-performance.bench.ts`

Purpose: Core navigation performance benchmarking and optimization
Benchmarks:

Navigation stack push/pop operation performance
Tab switching performance with large numbers of tabs
Route matching and parameter extraction performance
Navigation state serialization and persistence performance
Memory usage during complex navigation scenarios

`bundle-size.bench.ts`

Purpose: Bundle size impact analysis and tree-shaking effectiveness
Analysis:

Individual component bundle size impact
Tree-shaking effectiveness for unused navigation features
Comparison of Simple vs Enhanced vs Advanced TabView bundle sizes
Navigation system bundle size regression testing

📦 Distribution (`dist/`)

Optimized plugin distribution with granular exports

dist/
├── index.js                          # Main plugin entry point (ESM)
├── index.cjs                         # CommonJS compatibility
├── index.d.ts                       # TypeScript declarations
├── navigation-view.js               # NavigationView component
├── navigation-link.js               # NavigationLink component  
├── simple-tab-view.js              # Simple TabView (8KB)
├── enhanced-tab-view.js            # Enhanced TabView (15KB)
├── advanced-tab-view.js            # Advanced TabView (23KB)
├── navigation-stack.js             # Navigation stack management
├── navigation-router.js            # Routing system
├── programmatic-navigation.js      # Programmatic navigation API
├── navigation-modifiers.js         # Navigation modifiers
└── *.d.ts files                    # TypeScript declarations for all modules

Tree-Shaking Benefits:

Import only the navigation features you need
Simple TabView: ~8KB for basic tab functionality
Enhanced TabView: ~15KB for advanced tab features
Complete Navigation: ~23KB for full navigation system
Core Navigation Only: ~12KB for NavigationView and NavigationLink

typescript

// NavigationView with stack-based navigation
import { NavigationView, NavigationLink } from '@tachui/navigation'

const app = NavigationView([
  VStack([
    Text("Home Screen"),
    NavigationLink("Detail View", () => DetailScreen())
  ])
]).modifier
  .navigationTitle("My App")
  .build()

// TabView with multiple implementation options
import { SimpleTabView, EnhancedTabView, AdvancedTabView } from '@tachui/navigation'

// Simple TabView (8KB) - Basic tab functionality
const simpleTabs = SimpleTabView({
  tabs: [
    { title: "Home", content: () => HomeView() },
    { title: "Settings", content: () => SettingsView() }
  ]
})

// Enhanced TabView (15KB) - Advanced features
const enhancedTabs = EnhancedTabView({
  tabs: tabDefinitions,
  allowReordering: true,
  showBadges: true,
  customTabRenderer: customRenderer
})

// Advanced TabView (23KB) - Desktop-class features
const advancedTabs = AdvancedTabView({
  tabs: tabDefinitions,
  tabGroups: true,
  contextMenus: true,
  multiWindow: true
})

typescript

// Navigation hooks for reactive navigation
import { useNavigation, useRouter } from '@tachui/navigation'

const navigation = useNavigation()
const router = useRouter()

// Programmatic navigation
navigation.push("DetailView", { id: 123 })
navigation.pop()
navigation.replace("NewView")

// Route-based navigation
router.navigate("/user/123")
router.back()
router.forward()

// Navigation with custom transitions
navigation.push("DetailView", { 
  animated: true,
  transition: "slide",
  duration: 300
})

typescript

// Navigation-specific modifiers
const navigationView = NavigationView(content)
  .modifier
  .navigationTitle("My App")
  .navigationBarStyle("large")
  .navigationBarHidden(false)
  .navigationGesturesEnabled(true)
  .build()

const tabView = EnhancedTabView(tabs)
  .modifier
  .tabBarStyle("prominent")
  .tabBarHidden(false)
  .selectedTab(activeTabIndex)
  .build()

📈 Current Implementation Metrics

16 Source Files: Complete navigation functionality with modular architecture
7 Test Files: Comprehensive test coverage including performance and integration testing
3 TabView Implementations: Simple (8KB), Enhanced (15KB), Advanced (23KB) for different needs
Full Navigation System: Complete SwiftUI-compatible navigation with ~23KB total bundle
Performance: <16ms navigation transitions, <5ms tab switching
Browser Support: Full browser history integration with fallback support

🎯 Plugin Architecture Benefits

Modular Design: Import only the navigation features you need
Tree-Shakeable: Optimal bundle sizes with granular imports
SwiftUI Compatible: Familiar API for SwiftUI developers
Performance Optimized: Smooth animations and efficient memory management
Accessibility First: WCAG 2.1 AA compliant navigation patterns
TypeScript Native: Complete type safety with intelligent auto-completion

🏗️ Framework Integration

Reactive Navigation: Navigation state automatically updates UI through TachUI's signal system
Modifier Compatibility: All navigation components work with TachUI's modifier system
Theme Integration: Automatic theme support through TachUI's asset system
Error Handling: Integration with TachUI's error boundary and recovery system

🔄 Development Workflow Integration

The Navigation plugin integrates seamlessly with TachUI development:

Installation: npm install @tachui/navigation as peer dependency to @tachui/core
Selective Import: Import specific navigation components for optimal bundle size
Progressive Enhancement: Start with Simple TabView, upgrade to Enhanced/Advanced as needed
Theme Integration: Navigation components automatically respect TachUI theme system
Testing: Comprehensive test utilities for navigation behavior and performance
Production: Optimized builds with minimal bundle impact

Usage Examples

typescript

// Basic navigation app
import { NavigationView, NavigationLink } from '@tachui/navigation'

const MyApp = () => NavigationView([
  VStack([
    Text("Welcome to My App"),
    NavigationLink("Go to Settings", () => SettingsView()),
    NavigationLink("View Profile", () => ProfileView())
  ])
])

// Tabbed application with enhanced features
import { EnhancedTabView } from '@tachui/navigation'

const TabbedApp = () => EnhancedTabView({
  tabs: [
    { 
      title: "Home", 
      icon: "house",
      badge: notificationCount,
      content: () => HomeView() 
    },
    { 
      title: "Search", 
      icon: "search",
      content: () => SearchView() 
    },
    { 
      title: "Profile", 
      icon: "person",
      content: () => ProfileView() 
    }
  ]
}).modifier
  .tabBarStyle("prominent")
  .build()

This document serves as the definitive guide to TachUI's Navigation plugin structure. The Navigation plugin provides comprehensive navigation capabilities while maintaining the performance and developer experience standards of the TachUI framework.

TachUI Navigation Plugin Structure ​

📋 Overview ​

🎯 Root Level ​

📝 Root File Details ​

package.json ​

vitest.benchmark.config.ts ​

🧭 Core Navigation (navigation-view.ts, navigation-link.ts) ​

📝 Core Navigation Details ​

navigation-view.ts ​

navigation-link.ts ​

📑 Tab System (tab-view.ts, enhanced-tab-view.ts, advanced-tab-view.ts) ​

📝 Tab System Details ​

simple-tab-view.ts ​

enhanced-tab-view.ts ​

advanced-tab-view.ts ​

🗃️ Navigation Management (navigation-manager.ts, navigation-stack.ts) ​

📝 Navigation Management Details ​

navigation-manager.ts ​

navigation-stack.ts ​

🔗 Routing System (navigation-router.ts, navigation-path.ts) ​

📝 Routing System Details ​

navigation-router.ts ​

navigation-path.ts ​

⚡ Enhanced Features (programmatic-navigation.ts, enhanced-navigation-hooks.ts) ​

📝 Enhanced Features Details ​

programmatic-navigation.ts ​

enhanced-navigation-hooks.ts ​

🎨 Modifier Integration (navigation-modifiers.ts) ​

📝 Navigation Modifier Details ​

navigation-modifiers.ts ​

🌐 Environment Integration (navigation-environment.ts) ​

📝 Environment Integration Details ​

navigation-environment.ts ​

🏷️ Type Definitions (types.ts) ​

📝 Type Definition Details ​

types.ts ​

🧪 Comprehensive Testing (__tests__/) ​

📝 Test Coverage Details ​

navigation-stack.test.ts ​

enhanced-tab-view.test.ts ​

📊 Performance Benchmarking (benchmarks/) ​

📝 Benchmark Details ​

navigation-performance.bench.ts ​

bundle-size.bench.ts ​

📦 Distribution (dist/) ​

🎯 Navigation Plugin API Reference ​

Core Navigation Components ​

Programmatic Navigation ​

Navigation Modifiers ​

📊 Navigation Plugin Statistics ​

📈 Current Implementation Metrics ​

🎯 Plugin Architecture Benefits ​

🏗️ Framework Integration ​

🔄 Development Workflow Integration ​

Usage Examples ​

TachUI Navigation Plugin Structure

📋 Overview

🎯 Root Level

📝 Root File Details

`package.json`

`vitest.benchmark.config.ts`

🧭 Core Navigation (`navigation-view.ts`, `navigation-link.ts`)

📝 Core Navigation Details

`navigation-view.ts`

`navigation-link.ts`

📑 Tab System (`tab-view.ts`, `enhanced-tab-view.ts`, `advanced-tab-view.ts`)

📝 Tab System Details

`simple-tab-view.ts`

`enhanced-tab-view.ts`

`advanced-tab-view.ts`

🗃️ Navigation Management (`navigation-manager.ts`, `navigation-stack.ts`)

📝 Navigation Management Details

`navigation-manager.ts`

`navigation-stack.ts`

🔗 Routing System (`navigation-router.ts`, `navigation-path.ts`)

📝 Routing System Details

`navigation-router.ts`

`navigation-path.ts`

⚡ Enhanced Features (`programmatic-navigation.ts`, `enhanced-navigation-hooks.ts`)

📝 Enhanced Features Details

`programmatic-navigation.ts`

`enhanced-navigation-hooks.ts`

🎨 Modifier Integration (`navigation-modifiers.ts`)

📝 Navigation Modifier Details

`navigation-modifiers.ts`

🌐 Environment Integration (`navigation-environment.ts`)

📝 Environment Integration Details

`navigation-environment.ts`

🏷️ Type Definitions (`types.ts`)

📝 Type Definition Details

`types.ts`

🧪 Comprehensive Testing (`tests/`)

📝 Test Coverage Details

`navigation-stack.test.ts`

`enhanced-tab-view.test.ts`

📊 Performance Benchmarking (`benchmarks/`)

📝 Benchmark Details

`navigation-performance.bench.ts`

`bundle-size.bench.ts`

📦 Distribution (`dist/`)

🎯 Navigation Plugin API Reference

Core Navigation Components

Programmatic Navigation

Navigation Modifiers

📊 Navigation Plugin Statistics

📈 Current Implementation Metrics

🎯 Plugin Architecture Benefits

🏗️ Framework Integration

🔄 Development Workflow Integration

Usage Examples