@waysnx/ui-navigation

Enterprise-grade navigation framework from WaysNX - menus, sidebars, breadcrumbs, and advanced navigation patterns.

Overview

@waysnx/ui-navigation is a production-ready React component library that provides a complete set of navigation components and utilities for building modern web applications.

Features

• ✅ 10+ Navigation Components - Menu, Sidebar, Navbar, Breadcrumb, Tabs, Drawer, and more
• ✅ Advanced Patterns - Command palette, context menus, mega menus, wizard navigation
• ✅ Enterprise Features - Permission-based access, workspace switching, notifications
• ✅ Full TypeScript Support - Strict mode, complete type definitions
• ✅ Accessibility First - WCAG 2.2 AA, keyboard navigation, screen reader support
• ✅ Theme Support - Light, dark, and custom themes with CSS variables
• ✅ Storage Persistence - Favorites, recent items, sidebar state, theme preferences
• ✅ Router Agnostic - Adapters for React Router, Next.js, TanStack Router
• ✅ Performance Optimized - Memoization, lazy loading, virtualization ready
• ✅ Tree-shakeable - Only import what you need

Installation

See INSTALLATION.md

npm install @waysnx/ui-navigation

Quick Start

Basic Menu

import React from 'react';
import { Menu, NavigationProvider } from '@waysnx/ui-navigation';

const App = () => {
  const items = [
    { id: 'home', label: 'Home', href: '/' },
    { id: 'about', label: 'About', href: '/about' },
    { id: 'contact', label: 'Contact', href: '/contact' },
  ];

  return (
    <NavigationProvider initialItems={items}>
      <Menu items={items} />
    </NavigationProvider>
  );
};

Sidebar Navigation

import { Sidebar, useSidebar } from '@waysnx/ui-navigation';

function Layout() {
  const { isOpen, toggle } = useSidebar();

  return (
    <div>
      <button onClick={toggle}>Toggle Sidebar</button>
      <Sidebar isOpen={isOpen} items={menuItems} />
    </div>
  );
}

Breadcrumb Navigation

import { Breadcrumb, useBreadcrumb } from '@waysnx/ui-navigation';

function Page() {
  const { items } = useBreadcrumb([
    { id: 'home', label: 'Home', href: '/' },
    { id: 'products', label: 'Products', href: '/products' },
    { id: 'item', label: 'Item', href: '/products/item' },
  ]);

  return <Breadcrumb items={items} />;
}

Components

Core Navigation

• Menu - Basic menu component with nested items
• MenuBar - Horizontal menu bar
• Sidebar - Vertical sidebar navigation
• Navbar - Header navigation bar
• Header - Page header with navigation
• Breadcrumb - Breadcrumb trail navigation

Advanced Navigation

• ContextMenu - Right-click context menu
• MegaMenu - Large, multi-column menu
• TreeMenu - Tree-based hierarchical menu
• Tabs - Tab navigation
• Drawer - Side drawer/panel
• Pagination - Page navigation
• StepNavigation - Multi-step process navigation
• Wizard - Step-by-step wizard

Enterprise Navigation

• CommandPalette - Command palette search
• SearchNavigation - Search-driven navigation
• WorkspaceSwitcher - Workspace/organization switching
• UserMenu - User account menu
• NotificationCenter - Notification panel
• QuickActions - Quick action toolbar
• FavoritesMenu - Favorites/bookmarks menu
• RecentItems - Recently accessed items

Hooks

• useNavigation() - Access global navigation context
• useSidebar() - Manage sidebar state
• useMenu() - Manage menu state and operations
• useTabs() - Manage tab navigation
• useDrawer() - Manage drawer state
• useBreadcrumb() - Manage breadcrumb items
• useWorkspace() - Manage workspace switching
• useCommandPalette() - Manage command palette

Utilities

Menu Operations

• createMenu() - Create menu from items
• flattenMenu() - Flatten nested menu structure
• findMenuItem() - Find item by ID
• filterMenu() - Filter menu by predicate
• buildBreadcrumb() - Build breadcrumb trail
• generateMenuTree() - Generate menu tree from flat items
• sortMenuItems() - Sort menu items

Security & Permissions

• canAccessItem() - Check permission for item
• filterMenuByPermissions() - Filter by permissions
• requirePermission() - Mark item as requiring permission
• requireRole() - Mark item as requiring role

Storage

• saveFavorites() - Save favorites to storage
• getFavorites() - Get favorites from storage
• addRecentItem() - Add to recent items
• getRecentItems() - Get recent items
• exportNavigationData() - Export all navigation data
• importNavigationData() - Import navigation data

Theming

CSS Variables

All components use CSS custom properties for styling:

--nav-primary-color: rgb(59, 130, 246);
--nav-text-color: rgb(31, 41, 55);
--nav-background-color: rgb(255, 255, 255);
--nav-sidebar-width: 256px;
--nav-item-height: 40px;
/* ... and many more */

Theme Modes

import { NavigationProvider } from '@waysnx/ui-navigation';

<NavigationProvider initialItems={items}>
  <App />
</NavigationProvider>

Themes automatically respond to system preferences via prefers-color-scheme media query.

Accessibility

All components support:

• ✅ Keyboard navigation (Tab, Arrow keys, Enter, Escape)
• ✅ Screen reader labels (ARIA)
• ✅ Focus management
• ✅ High contrast mode
• ✅ Reduced motion support

Router Integration

React Router

import { createBrowserRouter } from 'react-router-dom';
import { NavigationProvider } from '@waysnx/ui-navigation';

const router = createBrowserRouter([...]);

<NavigationProvider routerAdapter={{
  isActive: (href) => location.pathname === href,
  navigate: (href) => navigate(href),
}}>
  <RouterProvider router={router} />
</NavigationProvider>

Next.js

'use client';
import { NavigationProvider } from '@waysnx/ui-navigation';
import { useRouter, usePathname } from 'next/navigation';

export function Layout({ children }) {
  const router = useRouter();
  const pathname = usePathname();

  return (
    <NavigationProvider routerAdapter={{
      isActive: (href) => pathname === href,
      navigate: (href) => router.push(href),
    }}>
      {children}
    </NavigationProvider>
  );
}

Permission-Based Navigation

Integrate with @waysnx/ui-security:

import { Menu } from '@waysnx/ui-navigation';
import { usePermissions } from '@waysnx/ui-security';

function Navigation() {
  const { permissions, roles, features } = usePermissions();

  return (
    <Menu
      items={menuItems}
      security={{ permissions, roles, features }}
    />
  );
}

Performance

• ✅ Memoized components prevent unnecessary re-renders
• ✅ Lazy rendering for large menus
• ✅ Virtualization support for scrollable lists
• ✅ Code splitting for better bundle size
• ✅ CSS-in-JS optimized for production

Browser Support

• Chrome/Edge: Latest 2 versions
• Firefox: Latest 2 versions
• Safari: Latest 2 versions
• Mobile: iOS 12+, Android 6+

Documentation

• INSTALLATION.md - Installation and setup
• DEVELOPMENT.md - Development guide
• Storybook - Interactive component explorer

Examples

See /examples directory for complete working examples.

Testing

npm run test          # Run tests
npm run test:ui       # Interactive test UI
npm run test:coverage # Coverage report

Contributing

See CONTRIBUTING.md

License

Apache 2.0 - See LICENSE

Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions
• 🤝 Contributing

Made with ❤️ by WaysNX Technologies