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

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