@breadstone/ziegel-platform-navigation

Navigation and routing infrastructure for the ziegel platform. Provides client-side routing, navigation guards, breadcrumbs, deep linking, and URL management for single-page applications.

Navigation: Enterprise navigation with routing, guards, breadcrumbs, and deep linking support.

🚀 Overview

@breadstone/ziegel-platform-navigation provides:

• Client-Side Routing: Hash and history-based routing
• Navigation Guards: Route protection and access control
• Breadcrumb Management: Automatic and custom breadcrumb generation
• Deep Linking: URL state management and restoration
• Route Parameters: Dynamic route parameters and query strings
• Navigation History: Browser history management
• Lazy Loading: Code splitting and lazy route loading

📦 Installation

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

🧩 Features & Usage Examples

Basic Routing

import { Router, Route, NavigationService } from '@breadstone/ziegel-platform-navigation';

const router = new Router();

// Define routes
router.addRoute(new Route({
  path: '/home',
  component: 'HomeComponent',
  title: 'Home'
}));

router.addRoute(new Route({
  path: '/users/:id',
  component: 'UserDetailComponent',
  title: 'User Details'
}));

router.addRoute(new Route({
  path: '/admin/*',
  component: 'AdminComponent',
  requiresAuth: true
}));

// Navigate programmatically
const navigation = new NavigationService(router);
await navigation.navigate('/users/123');

Navigation Guards

import { NavigationGuard, CanActivate, CanDeactivate } from '@breadstone/ziegel-platform-navigation';

class AuthGuard implements CanActivate {
  async canActivate(route: Route): Promise<boolean> {
    const isAuthenticated = await this.authService.isAuthenticated();
    if (!isAuthenticated) {
      this.navigation.navigate('/login');
      return false;
    }
    return true;
  }
}

class UnsavedChangesGuard implements CanDeactivate {
  async canDeactivate(component: any): Promise<boolean> {
    if (component.hasUnsavedChanges()) {
      return confirm('You have unsaved changes. Are you sure you want to leave?');
    }
    return true;
  }
}

// Apply guards to routes
router.addRoute(new Route({
  path: '/admin',
  component: 'AdminComponent',
  guards: [AuthGuard, UnsavedChangesGuard]
}));

Breadcrumb Management

import { BreadcrumbService, Breadcrumb } from '@breadstone/ziegel-platform-navigation';

const breadcrumbService = new BreadcrumbService();

// Auto-generate breadcrumbs from route hierarchy
breadcrumbService.enableAutoGeneration();

// Custom breadcrumbs
router.addRoute(new Route({
  path: '/users/:id/profile',
  component: 'UserProfileComponent',
  breadcrumb: (params) => new Breadcrumb({
    label: `User ${params.id}`,
    url: `/users/${params.id}`
  })
}));

// Get current breadcrumbs
const breadcrumbs = breadcrumbService.getCurrentBreadcrumbs();

Deep Linking

import { DeepLinkManager, UrlStateManager } from '@breadstone/ziegel-platform-navigation';

const deepLinkManager = new DeepLinkManager();
const urlStateManager = new UrlStateManager();

// Save component state to URL
urlStateManager.saveState('filters', {
  category: 'electronics',
  priceRange: [100, 500],
  sortBy: 'price'
});

// Restore state from URL
const filters = urlStateManager.getState('filters');

// Generate shareable URLs
const shareableUrl = deepLinkManager.generateLink('/products', {
  filters: filters,
  view: 'grid'
});

Route Parameters

import { RouteParams, QueryParams } from '@breadstone/ziegel-platform-navigation';

// Access route parameters
router.addRoute(new Route({
  path: '/users/:userId/posts/:postId',
  component: 'PostDetailComponent',
  onActivate: (params: RouteParams) => {
    const userId = params.get('userId');
    const postId = params.get('postId');
    console.log(`Loading post ${postId} for user ${userId}`);
  }
}));

// Access query parameters
const queryParams = new QueryParams(window.location.search);
const page = queryParams.get('page', 1);
const limit = queryParams.get('limit', 10);

Lazy Loading

import { LazyRoute, RouteModule } from '@breadstone/ziegel-platform-navigation';

// Lazy load route modules
router.addRoute(new LazyRoute({
  path: '/dashboard',
  loadComponent: () => import('./modules/dashboard/DashboardComponent'),
  loadModule: () => import('./modules/dashboard/DashboardModule')
}));

// Module-based lazy loading
router.addRoute(new RouteModule({
  path: '/admin',
  module: () => import('./modules/admin/AdminModule')
}));

Navigation History

import { NavigationHistory, HistoryEntry } from '@breadstone/ziegel-platform-navigation';

const history = new NavigationHistory();

// Navigate with history tracking
history.push('/users/123');
history.push('/users/123/edit');

// Go back
history.back();

// Go forward
history.forward();

// Get navigation history
const entries = history.getEntries();
const currentEntry = history.getCurrentEntry();

URL Management

import { UrlBuilder, UrlParser } from '@breadstone/ziegel-platform-navigation';

// Build URLs programmatically
const url = new UrlBuilder('/api/users')
  .addPathSegment('123')
  .addPathSegment('posts')
  .addQueryParam('page', 1)
  .addQueryParam('limit', 10)
  .build(); // /api/users/123/posts?page=1&limit=10

// Parse URLs
const parser = new UrlParser('/users/123/posts?page=1&limit=10');
const pathSegments = parser.getPathSegments(); // ['users', '123', 'posts']
const queryParams = parser.getQueryParams(); // { page: '1', limit: '10' }

📚 Package import points

import {
    // Core Navigation
    Router,
    Route,
    NavigationService,
    
    // Guards
    NavigationGuard,
    CanActivate,
    CanDeactivate,
    
    // Breadcrumbs
    BreadcrumbService,
    Breadcrumb,
    
    // Deep Linking
    DeepLinkManager,
    UrlStateManager,
    
    // Parameters
    RouteParams,
    QueryParams,
    
    // Lazy Loading
    LazyRoute,
    RouteModule,
    
    // History
    NavigationHistory,
    HistoryEntry,
    
    // URL Management
    UrlBuilder,
    UrlParser
} from '@breadstone/ziegel-platform-navigation';

📚 API Documentation

For detailed API documentation, visit: API Docs

Related Packages

• @breadstone/ziegel-platform: Core platform services
• @breadstone/ziegel-presentation: UI utilities and components
• @breadstone/ziegel-core: Foundation utilities

License

MIT

Issues

Please report bugs and feature requests in the Issue Tracker

Part of the ziegel Enterprise TypeScript Framework