{"id":28928201,"url":"https://github.com/ktsu-dev/navigation","last_synced_at":"2026-02-14T03:57:06.959Z","repository":{"id":296118073,"uuid":"992344782","full_name":"ktsu-dev/Navigation","owner":"ktsu-dev","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-03T03:04:17.000Z","size":254,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-03T16:58:49.059Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ktsu-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":"COPYRIGHT.md","agents":null,"dco":null,"cla":null}},"created_at":"2025-05-29T02:22:09.000Z","updated_at":"2026-02-03T03:01:24.000Z","dependencies_parsed_at":"2025-05-29T03:37:22.249Z","dependency_job_id":"3b5bd5dd-989a-4cfc-9015-4dddd6a6f193","html_url":"https://github.com/ktsu-dev/Navigation","commit_stats":null,"previous_names":["ktsu-dev/navigation"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/ktsu-dev/Navigation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktsu-dev%2FNavigation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktsu-dev%2FNavigation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktsu-dev%2FNavigation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktsu-dev%2FNavigation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ktsu-dev","download_url":"https://codeload.github.com/ktsu-dev/Navigation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktsu-dev%2FNavigation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29136034,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-05T21:59:57.939Z","status":"ssl_error","status_checked_at":"2026-02-05T21:59:57.628Z","response_time":65,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-22T14:12:27.995Z","updated_at":"2026-02-05T22:07:18.796Z","avatar_url":"https://github.com/ktsu-dev.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ktsu.Navigation\n\nA robust .NET library for implementing navigation stacks with undo/redo support and persistence capabilities.\n\n## Overview\n\n**ktsu.Navigation** provides a complete navigation stack implementation that supports:\n\n- **Forward/Backward Navigation**: Navigate through items with full browser-like back/forward functionality\n- **Undo/Redo Operations**: Complete undo/redo support for all navigation actions\n- **Persistence**: Save and restore navigation state to various storage backends\n- **Event-Driven Architecture**: React to navigation changes with comprehensive event notifications\n- **Generic Design**: Works with any navigation item type implementing `INavigationItem`\n- **Factory Pattern**: Easy creation of navigation stacks with different configurations\n\nPerfect for applications that need robust navigation management, such as:\n- Code editors with file navigation\n- Image viewers with browsing history\n- Document management systems\n- Any application requiring navigation state management\n\n## Features\n\n### Core Navigation\n- ✅ NavigateTo, GoBack, GoForward operations\n- ✅ Current item tracking with CanGoBack/CanGoForward status\n- ✅ Complete navigation history management\n- ✅ Forward history clearing when navigating to new items\n- ✅ Thread-safe operations\n\n### Undo/Redo System\n- ✅ Full undo/redo support for navigation operations\n- ✅ Configurable history size limits\n- ✅ State change notifications\n- ✅ Error handling during undo/redo operations\n\n### Persistence\n- ✅ JSON file persistence provider\n- ✅ In-memory persistence for testing\n- ✅ Async operations with cancellation token support\n- ✅ Custom persistence provider support\n\n### Events \u0026 Extensibility\n- ✅ Navigation change events (NavigateTo, GoBack, GoForward, Clear)\n- ✅ Metadata support for navigation items\n- ✅ Generic design for custom navigation item types\n- ✅ Factory pattern for easy configuration\n\n## Installation\n\nAdd the NuGet package:\n\n```bash\ndotnet add package ktsu.Navigation\n```\n\n## Quick Start\n\n### Basic Navigation\n\n```csharp\nusing ktsu.Navigation.Core.Models;\nusing ktsu.Navigation.Core.Services;\n\n// Create navigation items\nvar page1 = new NavigationItem(\"page1\", \"Home Page\");\nvar page2 = new NavigationItem(\"page2\", \"About Page\");\nvar page3 = new NavigationItem(\"page3\", \"Contact Page\");\n\n// Create a basic navigation stack\nvar navigation = new Navigation\u003cNavigationItem\u003e();\n\n// Navigate through items\nnavigation.NavigateTo(page1);  // Current: Home Page\nnavigation.NavigateTo(page2);  // Current: About Page\nnavigation.NavigateTo(page3);  // Current: Contact Page\n\n// Go back and forward\nvar previous = navigation.GoBack();    // Current: About Page\nvar next = navigation.GoForward();     // Current: Contact Page\n\n// Check navigation state\nConsole.WriteLine($\"Current: {navigation.Current?.DisplayName}\");\nConsole.WriteLine($\"Can go back: {navigation.CanGoBack}\");\nConsole.WriteLine($\"Can go forward: {navigation.CanGoForward}\");\n```\n\n### With Undo/Redo Support\n\n```csharp\nusing ktsu.Navigation.Core.Services;\n\n// Create navigation with undo/redo support\nvar undoRedoProvider = new SimpleUndoRedoProvider(maxHistorySize: 50);\nvar navigation = new Navigation\u003cNavigationItem\u003e(undoRedoProvider);\n\nnavigation.NavigateTo(page1);\nnavigation.NavigateTo(page2);\n\n// Undo the last navigation\nundoRedoProvider.Undo();  // Back to page1\n\n// Redo the navigation\nundoRedoProvider.Redo();  // Forward to page2 again\n```\n\n### With Persistence\n\n```csharp\nusing ktsu.Navigation.Core.Services;\n\n// Create navigation with JSON file persistence\nvar persistenceProvider = new JsonFilePersistenceProvider\u003cNavigationItem\u003e(\"navigation-state.json\");\nvar navigation = new Navigation\u003cNavigationItem\u003e(persistenceProvider: persistenceProvider);\n\nnavigation.NavigateTo(page1);\nnavigation.NavigateTo(page2);\n\n// Save navigation state\nawait navigation.SaveStateAsync();\n\n// Later... restore navigation state\nawait navigation.LoadStateAsync();\nConsole.WriteLine($\"Restored to: {navigation.Current?.DisplayName}\");\n```\n\n### Complete Example with All Features\n\n```csharp\nusing ktsu.Navigation.Core.Services;\n\n// Create providers\nvar undoRedoProvider = new SimpleUndoRedoProvider();\nvar persistenceProvider = new JsonFilePersistenceProvider\u003cNavigationItem\u003e(\"app-navigation.json\");\n\n// Create navigation stack with all features\nvar navigation = new Navigation\u003cNavigationItem\u003e(undoRedoProvider, persistenceProvider);\n\n// Subscribe to navigation events\nnavigation.NavigationChanged += (sender, e) =\u003e\n{\n    Console.WriteLine($\"Navigation: {e.NavigationType}\");\n    Console.WriteLine($\"From: {e.PreviousItem?.DisplayName ?? \"None\"}\");\n    Console.WriteLine($\"To: {e.CurrentItem?.DisplayName ?? \"None\"}\");\n};\n\n// Use factory for easier creation\nvar factory = new NavigationStackFactory(undoRedoProvider);\nvar anotherNavigation = factory.CreateNavigationStack\u003cNavigationItem\u003e(persistenceProvider);\n```\n\n### Custom Navigation Items\n\n```csharp\npublic class DocumentNavigationItem : INavigationItem\n{\n    public string Id { get; }\n    public string DisplayName { get; set; }\n    public DateTime CreatedAt { get; }\n    public IReadOnlyDictionary\u003cstring, object\u003e Metadata =\u003e _metadata.AsReadOnly();\n    \n    private readonly Dictionary\u003cstring, object\u003e _metadata = new();\n    \n    public DocumentNavigationItem(string filePath, string displayName)\n    {\n        Id = filePath;\n        DisplayName = displayName;\n        CreatedAt = DateTime.UtcNow;\n        SetMetadata(\"FilePath\", filePath);\n        SetMetadata(\"FileSize\", new FileInfo(filePath).Length);\n    }\n    \n    public void SetMetadata(string key, object value) =\u003e _metadata[key] = value;\n    public bool RemoveMetadata(string key) =\u003e _metadata.Remove(key);\n}\n\n// Use with navigation\nvar navigation = new Navigation\u003cDocumentNavigationItem\u003e();\nvar document = new DocumentNavigationItem(\"/path/to/file.txt\", \"My Document\");\nnavigation.NavigateTo(document);\n```\n\n## Architecture\n\nThe library follows clean architecture principles with well-separated concerns:\n\n- **Models**: `NavigationItem`, `NavigationState` - Core data structures\n- **Contracts**: Interfaces defining the contracts for all components\n- **Services**: Implementation classes for navigation, persistence, and undo/redo\n\n### Key Interfaces\n\n- `INavigation\u003cT\u003e`: Main navigation stack operations\n- `INavigationItem`: Contract for items that can be navigated to\n- `IPersistenceProvider\u003cT\u003e`: Contract for persistence implementations\n- `IUndoRedoProvider`: Contract for undo/redo implementations\n\n## Extension Points\n\nCreate custom persistence providers:\n\n```csharp\npublic class DatabasePersistenceProvider\u003cT\u003e : IPersistenceProvider\u003cT\u003e where T : INavigationItem\n{\n    public async Task SaveStateAsync(INavigationState\u003cT\u003e state, CancellationToken cancellationToken = default)\n    {\n        // Save to database\n    }\n    \n    public async Task\u003cINavigationState\u003cT\u003e?\u003e LoadStateAsync(CancellationToken cancellationToken = default)\n    {\n        // Load from database\n        return null;\n    }\n    \n    // Implement other interface methods...\n}\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT License. Copyright (c) ktsu.dev\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fktsu-dev%2Fnavigation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fktsu-dev%2Fnavigation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fktsu-dev%2Fnavigation/lists"}