# NavLink

## Description

A navigation link component that handles both internal routing and external links with automatic detection. Extends Button component functionality with router integration, supporting various styles, icons, and accessibility features for seamless navigation experiences.

## Aliases

- NavLink
- NavigationLink
- RouterLink
- MenuLink
- ActionLink

## Props Breakdown

**Extends:** `Omit<RouteLinkProps, 'to'>` + `Pick<ButtonProps, 'appearance' | 'size' | 'style' | 'leadingIcon' | 'trailingIcon'>`

| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `to` | `string \| -1` | - | Yes | Destination URL/path. External URLs (starting with "https") render as `<a>` tags, internal paths as RouterNavLink |
| `type` | `NavLinkTypeEnum \| ButtonTypeEnum` | `'Fill'` | No | Visual style type (Fill, Underline, etc.) |
| `appearance` | `string` | - | No | Visual appearance variant |
| `size` | `string` | - | No | Size variant of the link |
| `style` | `string` | - | No | Style variant for different contexts |
| `leadingIcon` | `ReactNode` | - | No | Icon displayed before the link text |
| `trailingIcon` | `ReactNode` | - | No | Icon displayed after the link text |
| `component-variant` | `string` | - | No | Override styling variant |
| `children` | `ReactNode` | - | Yes | Link content (text, icons, components like cards, etc.) |

Plus all React Router Link props and Button styling props.

## Examples

### Basic Usage
```tsx
import { NavLink, Icon } from '@delightui/components';

function BasicExample() {
  return (
    <div className="basic-nav-links">
      <NavLink to="/home">Home</NavLink>
      <NavLink to="/about">About Us</NavLink>
      <NavLink to="/contact">Contact</NavLink>
      <NavLink to="https://external-site.com">External Link</NavLink>
    </div>
  );
}
```

### Navigation Links with Icons
```tsx
function IconNavLinksExample() {
  return (
    <div className="icon-nav-links">
      <NavLink 
        to="/dashboard" 
        leadingIcon={<Icon icon="Dashboard" />}
      >
        Dashboard
      </NavLink>
      
      <NavLink 
        to="/projects" 
        leadingIcon={<Icon icon="Folder" />}
        trailingIcon={<Icon icon="ChevronRight" />}
      >
        Projects
      </NavLink>
      
      <NavLink 
        to="/settings" 
        leadingIcon={<Icon icon="Settings" />}
      >
        Settings
      </NavLink>
      
      <NavLink 
        to="https://help.example.com" 
        leadingIcon={<Icon icon="Help" />}
        trailingIcon={<Icon icon="ExternalLink" />}
      >
        Help Center
      </NavLink>
    </div>
  );
}
```

### Different Link Types
```tsx
function LinkTypesExample() {
  return (
    <div className="link-types">
      <NavLink to="/home" type="Fill">
        Fill Link
      </NavLink>
      
      <NavLink to="/about" type="Underline">
        Underline Link
      </NavLink>
      
      <NavLink to="/contact" type="Ghost">
        Ghost Link
      </NavLink>
      
      <NavLink to="/services" type="Outlined">
        Outlined Link
      </NavLink>
    </div>
  );
}
```

### Active State Navigation
```tsx
function ActiveStateExample() {
  const [currentPath, setCurrentPath] = useState('/dashboard');

  const navigationItems = [
    { path: '/dashboard', label: 'Dashboard', icon: 'Dashboard' },
    { path: '/projects', label: 'Projects', icon: 'Folder' },
    { path: '/team', label: 'Team', icon: 'People' },
    { path: '/reports', label: 'Reports', icon: 'Description' }
  ];

  return (
    <div className="active-nav">
      {navigationItems.map(item => (
        <NavLink
          key={item.path}
          to={item.path}
          className={currentPath === item.path ? 'active' : ''}
          onClick={() => setCurrentPath(item.path)}
          leadingIcon={<Icon icon={item.icon} />}
          style={currentPath === item.path ? 'Primary' : 'Default'}
        >
          {item.label}
        </NavLink>
      ))}
    </div>
  );
}
```

### Styled Navigation Links
```tsx
function StyledNavLinksExample() {
  return (
    <div className="styled-nav-links">
      <NavLink 
        to="/important" 
        style="Primary"
        leadingIcon={<Icon icon="Star" />}
      >
        Important Section
      </NavLink>
      
      <NavLink 
        to="/warning" 
        style="Warning"
        leadingIcon={<Icon icon="Warning" />}
      >
        Warning Area
      </NavLink>
      
      <NavLink 
        to="/danger" 
        style="Destructive"
        leadingIcon={<Icon icon="Error" />}
      >
        Danger Zone
      </NavLink>
      
      <NavLink 
        to="/success" 
        style="Success"
        leadingIcon={<Icon icon="CheckCircle" />}
      >
        Success Page
      </NavLink>
    </div>
  );
}
```

### Breadcrumb Navigation Links
```tsx
function BreadcrumbLinksExample() {
  const breadcrumbs = [
    { label: 'Home', path: '/' },
    { label: 'Products', path: '/products' },
    { label: 'Electronics', path: '/products/electronics' },
    { label: 'Smartphones', path: '/products/electronics/smartphones' }
  ];

  return (
    <div className="breadcrumb-links">
      {breadcrumbs.map((crumb, index) => (
        <div key={crumb.path} className="breadcrumb-item">
          <NavLink 
            to={crumb.path}
            type="Underline"
            size="Small"
          >
            {crumb.label}
          </NavLink>
          
          {index < breadcrumbs.length - 1 && (
            <Icon icon="ChevronRight" className="breadcrumb-separator" />
          )}
        </div>
      ))}
    </div>
  );
}
```

### Mobile Navigation Links
```tsx
function MobileNavLinksExample() {
  const [isMobileMenuOpen, setIsMobileMenuOpen] = useState(false);

  const navigationItems = [
    { to: '/home', label: 'Home', icon: 'Home' },
    { to: '/products', label: 'Products', icon: 'ShoppingCart' },
    { to: '/services', label: 'Services', icon: 'Build' },
    { to: '/about', label: 'About', icon: 'Info' },
    { to: '/contact', label: 'Contact', icon: 'Phone' }
  ];

  return (
    <div className="mobile-nav">
      <Button 
        className="mobile-toggle"
        onClick={() => setIsMobileMenuOpen(!isMobileMenuOpen)}
        leadingIcon={<Icon icon={isMobileMenuOpen ? 'Close' : 'Menu'} />}
      >
        Menu
      </Button>

      <div className={`mobile-nav-links ${isMobileMenuOpen ? 'open' : ''}`}>
        {navigationItems.map(item => (
          <NavLink
            key={item.to}
            to={item.to}
            leadingIcon={<Icon icon={item.icon} />}
            onClick={() => setIsMobileMenuOpen(false)}
            className="mobile-nav-link"
          >
            {item.label}
          </NavLink>
        ))}
      </div>
    </div>
  );
}
```

### Tab Navigation Links
```tsx
function TabNavigationExample() {
  const [activeTab, setActiveTab] = useState('overview');

  const tabs = [
    { id: 'overview', label: 'Overview', icon: 'Dashboard' },
    { id: 'details', label: 'Details', icon: 'Description' },
    { id: 'analytics', label: 'Analytics', icon: 'BarChart' },
    { id: 'settings', label: 'Settings', icon: 'Settings' }
  ];

  return (
    <div className="tab-navigation">
      <div className="tab-links">
        {tabs.map(tab => (
          <NavLink
            key={tab.id}
            to={`/project/${tab.id}`}
            className={activeTab === tab.id ? 'active-tab' : 'inactive-tab'}
            onClick={() => setActiveTab(tab.id)}
            leadingIcon={<Icon icon={tab.icon} />}
            type="Underline"
          >
            {tab.label}
          </NavLink>
        ))}
      </div>

      <div className="tab-content">
        {activeTab === 'overview' && (
          <div>Overview content...</div>
        )}
        {activeTab === 'details' && (
          <div>Project details...</div>
        )}
        {activeTab === 'analytics' && (
          <div>Analytics dashboard...</div>
        )}
        {activeTab === 'settings' && (
          <div>Project settings...</div>
        )}
      </div>
    </div>
  );
}
```

### External Links with Indicators
```tsx
function ExternalLinksExample() {
  const externalLinks = [
    { 
      url: 'https://github.com/company/repo', 
      label: 'GitHub Repository',
      icon: 'Code'
    },
    { 
      url: 'https://docs.example.com', 
      label: 'Documentation',
      icon: 'Book'
    },
    { 
      url: 'https://support.example.com', 
      label: 'Support Center',
      icon: 'Support'
    },
    { 
      url: 'https://blog.example.com', 
      label: 'Company Blog',
      icon: 'Article'
    }
  ];

  return (
    <div className="external-links">
      <Text type="Heading5">External Resources</Text>
      
      {externalLinks.map(link => (
        <NavLink
          key={link.url}
          to={link.url}
          leadingIcon={<Icon icon={link.icon} />}
          trailingIcon={<Icon icon="ExternalLink" />}
          className="external-link"
          target="_blank"
          rel="noopener noreferrer"
        >
          {link.label}
        </NavLink>
      ))}
    </div>
  );
}
```

### Conditional Navigation Links
```tsx
function ConditionalLinksExample() {
  const [user, setUser] = useState({
    isAuthenticated: true,
    role: 'admin',
    permissions: ['read', 'write', 'admin']
  });

  const hasPermission = (permission) => {
    return user.permissions.includes(permission);
  };

  return (
    <div className="conditional-nav">
      {/* Always visible */}
      <NavLink to="/dashboard" leadingIcon={<Icon icon="Dashboard" />}>
        Dashboard
      </NavLink>

      {/* Authenticated users only */}
      {user.isAuthenticated && (
        <>
          <NavLink to="/profile" leadingIcon={<Icon icon="Person" />}>
            Profile
          </NavLink>
          
          <NavLink to="/projects" leadingIcon={<Icon icon="Folder" />}>
            My Projects
          </NavLink>
        </>
      )}

      {/* Permission-based navigation */}
      {hasPermission('admin') && (
        <>
          <NavLink 
            to="/admin/users" 
            leadingIcon={<Icon icon="People" />}
            style="Warning"
          >
            User Management
          </NavLink>
          
          <NavLink 
            to="/admin/settings" 
            leadingIcon={<Icon icon="Settings" />}
            style="Warning"
          >
            System Settings
          </NavLink>
        </>
      )}

      {/* Role-based navigation */}
      {user.role === 'admin' && (
        <NavLink 
          to="/admin/logs" 
          leadingIcon={<Icon icon="Description" />}
          style="Destructive"
        >
          System Logs
        </NavLink>
      )}

      {/* Unauthenticated users */}
      {!user.isAuthenticated && (
        <>
          <NavLink to="/login" style="Primary">
            Sign In
          </NavLink>
          
          <NavLink to="/register" type="Outlined">
            Sign Up
          </NavLink>
        </>
      )}
    </div>
  );
}
```

### Navigation Links with Loading States
```tsx
function LoadingStateLinksExample() {
  const [loadingStates, setLoadingStates] = useState({});

  const handleNavClick = async (path) => {
    setLoadingStates(prev => ({ ...prev, [path]: true }));
    
    // Simulate navigation delay
    await new Promise(resolve => setTimeout(resolve, 1500));
    
    setLoadingStates(prev => ({ ...prev, [path]: false }));
    // Navigate to the path
  };

  return (
    <div className="loading-nav-links">
      <NavLink
        to="/dashboard"
        leadingIcon={
          loadingStates['/dashboard'] ? (
            <Spinner size="Small" />
          ) : (
            <Icon icon="Dashboard" />
          )
        }
        onClick={(e) => {
          e.preventDefault();
          handleNavClick('/dashboard');
        }}
        disabled={loadingStates['/dashboard']}
      >
        Dashboard
        {loadingStates['/dashboard'] && (
          <Text type="BodySmall">Loading...</Text>
        )}
      </NavLink>

      <NavLink
        to="/reports"
        leadingIcon={
          loadingStates['/reports'] ? (
            <Spinner size="Small" />
          ) : (
            <Icon icon="Description" />
          )
        }
        onClick={(e) => {
          e.preventDefault();
          handleNavClick('/reports');
        }}
        disabled={loadingStates['/reports']}
      >
        Reports
        {loadingStates['/reports'] && (
          <Text type="BodySmall">Loading...</Text>
        )}
      </NavLink>
    </div>
  );
}
```

### Wrapping Complex Components (Cards)
```tsx
function CardNavigationExample() {
  const dashboardCards = [
    {
      id: 'analytics',
      title: 'Analytics Dashboard',
      description: 'View detailed analytics and metrics',
      icon: 'BarChart',
      path: '/dashboard/analytics'
    },
    {
      id: 'users',
      title: 'User Management',
      description: 'Manage users and permissions',
      icon: 'People',
      path: '/dashboard/users'
    },
    {
      id: 'settings',
      title: 'System Settings',
      description: 'Configure application settings',
      icon: 'Settings',
      path: '/dashboard/settings'
    }
  ];

  return (
    <div className="card-navigation-grid">
      {dashboardCards.map(card => (
        <NavLink key={card.id} to={card.path} className="card-nav-link">
          <Card className="dashboard-card">
            <CardHeader>
              <Icon icon={card.icon} size="Large" />
              <Text type="Heading4">{card.title}</Text>
            </CardHeader>
            <CardContent>
              <Text type="Body">{card.description}</Text>
            </CardContent>
          </Card>
        </NavLink>
      ))}
    </div>
  );
}
```

### Wrapping Complex Components (List Items)
```tsx
function NavigableListExample() {
  const projectItems = [
    {
      id: 1,
      name: 'E-commerce Platform',
      status: 'Active',
      lastUpdated: '2024-01-15',
      path: '/projects/ecommerce'
    },
    {
      id: 2,
      name: 'Mobile App Redesign',
      status: 'In Progress',
      lastUpdated: '2024-01-14',
      path: '/projects/mobile-app'
    },
    {
      id: 3,
      name: 'Analytics Dashboard',
      status: 'Completed',
      lastUpdated: '2024-01-10',
      path: '/projects/analytics'
    }
  ];

  return (
    <div className="navigable-list">
      {projectItems.map(project => (
        <NavLink key={project.id} to={project.path} className="list-nav-link">
          <ListItem className="project-item">
            <ListItemContent>
              <div className="project-header">
                <Text type="Heading5">{project.name}</Text>
                <Chip type={project.status === 'Active' ? 'Success' : 'Default'}>
                  {project.status}
                </Chip>
              </div>
              <Text type="BodySmall" className="project-date">
                Last updated: {project.lastUpdated}
              </Text>
            </ListItemContent>
            <ListItemAction>
              <Icon icon="ChevronRight" />
            </ListItemAction>
          </ListItem>
        </NavLink>
      ))}
    </div>
  );
}
```

### Wrapping Complex Components (Panels)
```tsx
function PanelNavigationExample() {
  const toolPanels = [
    {
      id: 'editor',
      title: 'Code Editor',
      description: 'Edit and manage your code files',
      icon: 'Code',
      path: '/tools/editor',
      isActive: true
    },
    {
      id: 'debugger',
      title: 'Debugger',
      description: 'Debug and troubleshoot your applications',
      icon: 'Bug',
      path: '/tools/debugger',
      isActive: false
    },
    {
      id: 'terminal',
      title: 'Terminal',
      description: 'Access command line interface',
      icon: 'Terminal',
      path: '/tools/terminal',
      isActive: false
    }
  ];

  return (
    <div className="panel-navigation">
      {toolPanels.map(panel => (
        <NavLink key={panel.id} to={panel.path} className="panel-nav-link">
          <Panel className={`tool-panel ${panel.isActive ? 'active' : ''}`}>
            <PanelHeader>
              <Icon icon={panel.icon} />
              <Text type="Heading5">{panel.title}</Text>
              {panel.isActive && (
                <Chip type="Primary" size="Small">Active</Chip>
              )}
            </PanelHeader>
            <PanelContent>
              <Text type="Body">{panel.description}</Text>
            </PanelContent>
          </Panel>
        </NavLink>
      ))}
    </div>
  );
}
```