@delightui/components 0.1.105 → 0.1.107

package/docs/components/molecules/NavLink.md

@@ -0,0 +1,499 @@
+# 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, 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>
+  );
+}
+```