ktsu.Navigation

Overview

Features

Core Navigation

Undo/Redo System

Persistence

Events & Extensibility

Installation

dotnet add package ktsu.Navigation

Quick Start

Basic Navigation

using ktsu.Navigation.Models;
using ktsu.Navigation.Services;

// Create navigation items
var page1 = new NavigationItem("page1", "Home Page");
var page2 = new NavigationItem("page2", "About Page");
var page3 = new NavigationItem("page3", "Contact Page");

// Create a navigation stack
var navigation = new Navigation<NavigationItem>();

// Navigate through items
navigation.NavigateTo(page1);  // Current: Home Page
navigation.NavigateTo(page2);  // Current: About Page
navigation.NavigateTo(page3);  // Current: Contact Page

// Go back and forward
var previous = navigation.GoBack();    // Current: About Page
var next = navigation.GoForward();     // Current: Contact Page

// Check navigation state
Console.WriteLine($"Current: {navigation.Current?.DisplayName}");
Console.WriteLine($"Can go back: {navigation.CanGoBack}");
Console.WriteLine($"Can go forward: {navigation.CanGoForward}");

With Undo/Redo Support

using ktsu.Navigation.Services;

// Create navigation with undo/redo support
var undoRedoProvider = new SimpleUndoRedoProvider(maxHistorySize: 50);
var navigation = new Navigation<NavigationItem>(undoRedoProvider);

navigation.NavigateTo(page1);
navigation.NavigateTo(page2);

// Undo the last navigation
undoRedoProvider.Undo();  // Back to page1

// Redo the navigation
undoRedoProvider.Redo();  // Forward to page2 again

With Persistence

using ktsu.Navigation.Services;

// Create navigation with JSON file persistence
var persistenceProvider = new JsonFilePersistenceProvider<NavigationItem>("navigation-state.json");
var navigation = new Navigation<NavigationItem>(undoRedoProvider: null, persistenceProvider: persistenceProvider);

navigation.NavigateTo(page1);
navigation.NavigateTo(page2);

// Save navigation state
await navigation.SaveStateAsync();

// Later... restore navigation state
await navigation.LoadStateAsync();
Console.WriteLine($"Restored to: {navigation.Current?.DisplayName}");

Saving subclasses of the item type

using System.Text.Json;
using System.Text.Json.Serialization.Metadata;

var options = new JsonSerializerOptions
{
    WriteIndented = true,
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    TypeInfoResolver = new DefaultJsonTypeInfoResolver
    {
        Modifiers =
        {
            typeInfo =>
            {
                if (typeInfo.Type == typeof(NavigationItem))
                {
                    typeInfo.PolymorphismOptions = new JsonPolymorphismOptions
                    {
                        DerivedTypes = { new JsonDerivedType(typeof(DocumentPage), "document") },
                    };
                }
            },
        },
    },
};

var persistenceProvider = new JsonFilePersistenceProvider<NavigationItem>("navigation-state.json", options);

Complete Example with All Features

using ktsu.Navigation.Services;

// Create providers
var undoRedoProvider = new SimpleUndoRedoProvider();
var persistenceProvider = new JsonFilePersistenceProvider<NavigationItem>("app-navigation.json");

// Create navigation with all features
var navigation = new Navigation<NavigationItem>(undoRedoProvider, persistenceProvider);

// Subscribe to navigation events
navigation.NavigationChanged += (sender, e) =>
{
    Console.WriteLine($"Navigation: {e.NavigationType}");
    Console.WriteLine($"From: {e.PreviousItem?.DisplayName ?? "None"}");
    Console.WriteLine($"To: {e.CurrentItem?.DisplayName ?? "None"}");
};

// Use factory for easier creation
var factory = new NavigationStackFactory(undoRedoProvider);
var anotherNavigation = factory.CreateNavigationStack<NavigationItem>(undoRedoProvider, persistenceProvider);

Custom Navigation Items

public class DocumentNavigationItem : INavigationItem
{
    public string Id { get; }
    public string DisplayName { get; set; }
    public DateTime CreatedAt { get; }
    public IReadOnlyDictionary<string, object> Metadata => _metadata.AsReadOnly();
    
    private readonly Dictionary<string, object> _metadata = new();
    
    public DocumentNavigationItem(string filePath, string displayName)
        : this(filePath, displayName, DateTime.UtcNow, null)
    {
        SetMetadata("FilePath", filePath);
        SetMetadata("FileSize", new FileInfo(filePath).Length);
    }
    
    // JsonFilePersistenceProvider reloads saved items through this constructor. System.Text.Json
    // needs each parameter to have the same name and type as the property it sets.
    [JsonConstructor]
    public DocumentNavigationItem(string id, string displayName, DateTime createdAt, IReadOnlyDictionary<string, object>? metadata)
    {
        Id = id;
        DisplayName = displayName;
        CreatedAt = createdAt;
        foreach (var entry in metadata ?? new Dictionary<string, object>())
        {
            _metadata[entry.Key] = entry.Value;
        }
    }
    
    public void SetMetadata(string key, object value) => _metadata[key] = value;
    public bool RemoveMetadata(string key) => _metadata.Remove(key);
}

// Use with navigation
var navigation = new Navigation<DocumentNavigationItem>();
var document = new DocumentNavigationItem("/path/to/file.txt", "My Document");
navigation.NavigateTo(document);

Architecture

Key Interfaces

Extension Points

public class DatabasePersistenceProvider<T> : IPersistenceProvider<T> where T : INavigationItem
{
    public async Task SaveStateAsync(INavigationState<T> state, CancellationToken cancellationToken = default)
    {
        // Save to database
        await Task.CompletedTask;
    }

    public async Task<INavigationState<T>?> LoadStateAsync(CancellationToken cancellationToken = default)
    {
        // Load from database
        return await Task.FromResult<INavigationState<T>?>(null);
    }

    // Implement HasSavedState, ClearState, etc.
}

Contributing

License