Navigation Platform Package

The @breadstone/ziegel-platform-navigation package provides a comprehensive navigation management system for applications, offering navigation services, routing capabilities, and navigation state management.

Installation

npm install @breadstone/ziegel-platform-navigation
# or
yarn add @breadstone/ziegel-platform-navigation

Core Concepts

The navigation package provides:

• Navigation Service: Centralized navigation management
• Navigation Items: Hierarchical navigation structure
• Navigation Journal: Navigation history tracking
• Navigation Context: Current navigation state

Usage

Basic Navigation Setup

import {
  NavigationService,
  NavigationServiceLocator,
  NavigationJournal,
  NavigationItem,
  INavigationService
} from '@breadstone/ziegel-platform-navigation';

// Create a navigation journal for history tracking
const journal = new NavigationJournal();

// Create the navigation service
const navigationService = new NavigationService(journal);

// Register with service locator
NavigationServiceLocator.registerInstance(navigationService);

Defining Navigation Items

import { NavigationItem, INavigationItemData } from '@breadstone/ziegel-platform-navigation';

// Create navigation items
const homeNavigation = new NavigationItem({
  id: 'home',
  title: 'Home',
  url: '/home',
  icon: 'home-icon',
  order: 0
});

const aboutNavigation = new NavigationItem({
  id: 'about',
  title: 'About',
  url: '/about',
  icon: 'info-icon',
  order: 1,
  parent: 'main-menu'
});

// Register navigation items
navigationService.register([homeNavigation, aboutNavigation]);

Hierarchical Navigation

// Create nested navigation structure
const mainMenu = new NavigationItem({
  id: 'main-menu',
  title: 'Main Menu',
  url: '/menu',
  children: [
    {
      id: 'products',
      title: 'Products',
      url: '/products',
      children: [
        { id: 'product-list', title: 'All Products', url: '/products/list' },
        { id: 'new-product', title: 'New Product', url: '/products/new' }
      ]
    },
    {
      id: 'settings',
      title: 'Settings',
      url: '/settings'
    }
  ]
});

navigationService.register(mainMenu);

Navigation with Parameters

import { NavigationParameters } from '@breadstone/ziegel-platform-navigation';

// Navigate with parameters
const productNavigation = new NavigationItem({
  id: 'product-detail',
  title: 'Product Detail',
  url: '/products/:id',
  parameters: new NavigationParameters({
    id: 'required'
  })
});

// Navigate to specific product
navigationService.navigate(productNavigation, { id: '123' });

Using Navigation Decorator

import { Navigation } from '@breadstone/ziegel-platform-navigation';

// Decorate classes with navigation metadata
@Navigation({
  id: 'user-profile',
  title: 'User Profile',
  url: '/profile',
  requiresAuth: true
})
export class UserProfileComponent {
  // Component implementation
}

Advanced Features

Navigation Context

import { NavigationContext } from '@breadstone/ziegel-platform-navigation';

// Access current navigation context
const context = NavigationContext.current;

console.log('Current route:', context.currentRoute);
console.log('Navigation params:', context.parameters);
console.log('Breadcrumb trail:', context.breadcrumbs);

Navigation Journal

// Access navigation history
const history = journal.getHistory();

// Navigate back
journal.goBack();

// Navigate forward
journal.goForward();

// Clear history
journal.clear();

Custom Navigation Logic

class CustomNavigationService extends NavigationService {
  public navigate(item: INavigationItem, params?: any): void {
    // Custom pre-navigation logic
    this.validateNavigation(item);

    // Call base navigation
    super.navigate(item);

    // Custom post-navigation logic
    this.trackNavigation(item);
  }

  private validateNavigation(item: INavigationItem): void {
    // Implement custom validation
    if (item.requiresAuth && !this.isAuthenticated()) {
      throw new Error('Authentication required');
    }
  }

  private trackNavigation(item: INavigationItem): void {
    // Track navigation for analytics
    console.log(`Navigated to: ${item.title}`);
  }
}

Configuration Options

Navigation Item Configuration

interface INavigationItemData {
  id: string;
  title: string;
  url: string;
  icon?: string;
  order?: number;
  parent?: string;
  children?: INavigationItemData[];
  visible?: boolean;
  enabled?: boolean;
  requiresAuth?: boolean;
  roles?: string[];
  metadata?: Record<string, any>;
}

Service Configuration

// Configure navigation service
const config = {
  enableJournal: true,
  maxHistorySize: 50,
  enableBreadcrumbs: true,
  autoRegisterRoutes: true
};

const navigationService = new NavigationService(journal, config);

Integration Examples

React Integration

import React, { useEffect, useState } from 'react';
import { NavigationServiceLocator } from '@breadstone/ziegel-platform-navigation';

export const NavigationMenu: React.FC = () => {
  const [navigationItems, setNavigationItems] = useState([]);

  useEffect(() => {
    const service = NavigationServiceLocator.getInstance();
    setNavigationItems(service.items);
  }, []);

  return (
    <nav&gt;
      {navigationItems.map(item => (
        <a key={item.id} href={item.url}>
          {item.title}
        </a&gt;
      ))}
    </nav&gt;
  );
};

Angular Integration

import { Injectable } from '@angular/core';
import { Router } from '@angular/router';
import { NavigationServiceLocator } from '@breadstone/ziegel-platform-navigation';

@Injectable({
  providedIn: 'root'
})
export class AngularNavigationService {
  private navigationService = NavigationServiceLocator.getInstance();

  constructor(private router: Router) {}

  public navigateTo(itemId: string, params?: any): void {
    const item = this.navigationService.getItem(itemId);
    if (item) {
      this.router.navigate([item.url], { queryParams: params });
    }
  }
}

Best Practices

1. Hierarchical Organization

// Organize navigation in logical hierarchies
const navigation = {
  main: [
    { id: 'dashboard', title: 'Dashboard', url: '/dashboard' },
    {
      id: 'admin',
      title: 'Administration',
      children: [
        { id: 'users', title: 'Users', url: '/admin/users' },
        { id: 'settings', title: 'Settings', url: '/admin/settings' }
      ]
    }
  ]
};

2. Route Parameterization

// Use parameterized routes for dynamic content
const routes = [
  { id: 'user-detail', url: '/users/:userId', title: 'User Detail' },
  { id: 'post-edit', url: '/posts/:postId/edit', title: 'Edit Post' }
];

3. Security Integration

// Integrate with authentication/authorization
@Navigation({
  id: 'admin-panel',
  title: 'Admin Panel',
  url: '/admin',
  requiresAuth: true,
  roles: ['administrator']
})
export class AdminPanelComponent {}

4. Performance Optimization

// Lazy load navigation items
const lazyNavigationLoader = {
  async loadNavigationItems(): Promise<INavigationItem[]> {
    const response = await fetch('/api/navigation');
    return response.json();
  }
};

Migration Guide

From Version 0.0.1 to 0.0.2

The navigation package has been enhanced with better TypeScript support and improved service integration.

Breaking Changes

• NavigationService constructor now requires a journal parameter
• Navigation items must implement INavigationItem interface

Migration Steps

// Before (v0.0.1)
const service = new NavigationService();

// After (v0.0.2)
const journal = new NavigationJournal();
const service = new NavigationService(journal);

Related Packages

• @breadstone/ziegel-platform: Core platform services
• @breadstone/ziegel-platform-messaging: Event messaging system
• @breadstone/ziegel-platform-logging: Logging infrastructure
• @breadstone/ziegel-presentation: UI presentation layer

Troubleshooting

Common Issues

1. Navigation not working: Ensure NavigationService is properly registered with ServiceLocator
2. Route parameters not passed: Check NavigationParameters configuration
3. History not tracking: Verify NavigationJournal is properly initialized

Debug Mode

// Enable debug logging
const service = new NavigationService(journal, { debug: true });

API Reference

For detailed API documentation, see the auto-generated API reference.

NavigationService

• navigate(item: INavigationItem): void - Navigate to a specific item
• register(items: INavigationItem | INavigationItem[]): void - Register navigation items
• getItem(id: string): INavigationItem | undefined - Get navigation item by ID
• items: ReadonlyArray<INavigationItem> - Get all registered items

NavigationJournal

• recordNavigation(data: INavigationItemData): void - Record navigation in history
• goBack(): void - Navigate to previous item
• goForward(): void - Navigate to next item
• getHistory(): INavigationItemData[] - Get navigation history