@delightui/components 0.1.105 → 0.1.107

package/docs/components/molecules/Nav.md

@@ -0,0 +1,530 @@
+# Nav
+
+## Description
+
+A navigation container component that provides semantic structure for navigation menus and lists. Serves as a flexible wrapper for organizing navigation items, links, and other navigation-related content with proper accessibility semantics and keyboard navigation support.
+
+## Aliases
+
+- Nav
+- Navigation
+- NavContainer
+- NavigationMenu
+- NavBar
+
+## Props Breakdown
+
+**Extends:** `HTMLAttributes<HTMLElement>`
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `children` | `ReactNode` | - | Yes | Navigation items, links, or other content to display |
+| `className` | `string` | - | No | Additional CSS class names for custom styling |
+| `role` | `string` | `'navigation'` | No | ARIA role for accessibility |
+| `aria-label` | `string` | - | No | Accessible label for screen readers |
+
+Plus all standard HTML element attributes (`id`, `style`, `onClick`, etc.).
+
+## Examples
+
+### Basic Usage
+```tsx
+import { Nav, NavItem, NavLink } from '@delightui/components';
+
+function BasicExample() {
+  return (
+    <Nav aria-label="Main navigation">
+      <NavItem>
+        <NavLink to="/home">Home</NavLink>
+      </NavItem>
+      <NavItem>
+        <NavLink to="/about">About</NavLink>
+      </NavItem>
+      <NavItem>
+        <NavLink to="/contact">Contact</NavLink>
+      </NavItem>
+    </Nav>
+  );
+}
+```
+
+### Horizontal Navigation Bar
+```tsx
+function HorizontalNavExample() {
+  return (
+    <Nav className="horizontal-nav" aria-label="Primary navigation">
+      <NavItem>
+        <NavLink to="/" leadingIcon={<Icon icon="Home" />}>
+          Dashboard
+        </NavLink>
+      </NavItem>
+      <NavItem>
+        <NavLink to="/projects" leadingIcon={<Icon icon="Folder" />}>
+          Projects
+        </NavLink>
+      </NavItem>
+      <NavItem>
+        <NavLink to="/team" leadingIcon={<Icon icon="People" />}>
+          Team
+        </NavLink>
+      </NavItem>
+      <NavItem>
+        <NavLink to="/settings" leadingIcon={<Icon icon="Settings" />}>
+          Settings
+        </NavLink>
+      </NavItem>
+    </Nav>
+  );
+}
+```
+
+### Vertical Sidebar Navigation
+```tsx
+function SidebarNavExample() {
+  const [activeSection, setActiveSection] = useState('dashboard');
+
+  return (
+    <Nav className="sidebar-nav" aria-label="Sidebar navigation">
+      <NavItem>
+        <NavLink 
+          to="/dashboard"
+          className={activeSection === 'dashboard' ? 'active' : ''}
+          leadingIcon={<Icon icon="Dashboard" />}
+        >
+          Dashboard
+        </NavLink>
+      </NavItem>
+      
+      <NavItem>
+        <NavLink 
+          to="/analytics"
+          className={activeSection === 'analytics' ? 'active' : ''}
+          leadingIcon={<Icon icon="Analytics" />}
+        >
+          Analytics
+        </NavLink>
+      </NavItem>
+      
+      <NavItem>
+        <NavLink 
+          to="/reports"
+          className={activeSection === 'reports' ? 'active' : ''}
+          leadingIcon={<Icon icon="Report" />}
+        >
+          Reports
+        </NavLink>
+      </NavItem>
+      
+      <NavItem>
+        <NavLink 
+          to="/users"
+          className={activeSection === 'users' ? 'active' : ''}
+          leadingIcon={<Icon icon="Person" />}
+        >
+          Users
+        </NavLink>
+      </NavItem>
+    </Nav>
+  );
+}
+```
+
+### Navigation with Nested Sections
+```tsx
+function NestedNavExample() {
+  const [expandedSections, setExpandedSections] = useState(new Set());
+
+  const toggleSection = (section) => {
+    const newExpanded = new Set(expandedSections);
+    if (newExpanded.has(section)) {
+      newExpanded.delete(section);
+    } else {
+      newExpanded.add(section);
+    }
+    setExpandedSections(newExpanded);
+  };
+
+  return (
+    <Nav className="nested-nav" aria-label="Application navigation">
+      <NavItem>
+        <NavLink to="/dashboard">Dashboard</NavLink>
+      </NavItem>
+      
+      <NavItem>
+        <Button 
+          type="Ghost"
+          onClick={() => toggleSection('content')}
+          trailingIcon={
+            <Icon 
+              icon={expandedSections.has('content') ? 'ExpandLess' : 'ExpandMore'} 
+            />
+          }
+        >
+          Content Management
+        </Button>
+        
+        {expandedSections.has('content') && (
+          <Nav className="nested-nav-items">
+            <NavItem>
+              <NavLink to="/content/posts">Posts</NavLink>
+            </NavItem>
+            <NavItem>
+              <NavLink to="/content/pages">Pages</NavLink>
+            </NavItem>
+            <NavItem>
+              <NavLink to="/content/media">Media</NavLink>
+            </NavItem>
+          </Nav>
+        )}
+      </NavItem>
+      
+      <NavItem>
+        <Button 
+          type="Ghost"
+          onClick={() => toggleSection('admin')}
+          trailingIcon={
+            <Icon 
+              icon={expandedSections.has('admin') ? 'ExpandLess' : 'ExpandMore'} 
+            />
+          }
+        >
+          Administration
+        </Button>
+        
+        {expandedSections.has('admin') && (
+          <Nav className="nested-nav-items">
+            <NavItem>
+              <NavLink to="/admin/users">User Management</NavLink>
+            </NavItem>
+            <NavItem>
+              <NavLink to="/admin/roles">Roles & Permissions</NavLink>
+            </NavItem>
+            <NavItem>
+              <NavLink to="/admin/system">System Settings</NavLink>
+            </NavItem>
+          </Nav>
+        )}
+      </NavItem>
+    </Nav>
+  );
+}
+```
+
+### Responsive Navigation
+```tsx
+function ResponsiveNavExample() {
+  const [isMobileMenuOpen, setIsMobileMenuOpen] = useState(false);
+
+  return (
+    <>
+      {/* Mobile Menu Toggle */}
+      <Button 
+        className="mobile-menu-toggle"
+        onClick={() => setIsMobileMenuOpen(!isMobileMenuOpen)}
+        aria-label="Toggle navigation menu"
+      >
+        <Icon icon={isMobileMenuOpen ? 'Close' : 'Menu'} />
+      </Button>
+
+      {/* Navigation */}
+      <Nav 
+        className={`responsive-nav ${isMobileMenuOpen ? 'mobile-open' : ''}`}
+        aria-label="Main navigation"
+      >
+        <NavItem>
+          <NavLink to="/" onClick={() => setIsMobileMenuOpen(false)}>
+            Home
+          </NavLink>
+        </NavItem>
+        <NavItem>
+          <NavLink to="/products" onClick={() => setIsMobileMenuOpen(false)}>
+            Products
+          </NavLink>
+        </NavItem>
+        <NavItem>
+          <NavLink to="/services" onClick={() => setIsMobileMenuOpen(false)}>
+            Services
+          </NavLink>
+        </NavItem>
+        <NavItem>
+          <NavLink to="/about" onClick={() => setIsMobileMenuOpen(false)}>
+            About
+          </NavLink>
+        </NavItem>
+        <NavItem>
+          <NavLink to="/contact" onClick={() => setIsMobileMenuOpen(false)}>
+            Contact
+          </NavLink>
+        </NavItem>
+      </Nav>
+    </>
+  );
+}
+```
+
+### Navigation with User Actions
+```tsx
+function UserActionNavExample() {
+  const [user, setUser] = useState({
+    name: 'John Doe',
+    avatar: '/user-avatar.jpg'
+  });
+
+  return (
+    <Nav className="header-nav" aria-label="User navigation">
+      {/* Main Navigation */}
+      <div className="nav-section">
+        <NavItem>
+          <NavLink to="/dashboard">Dashboard</NavLink>
+        </NavItem>
+        <NavItem>
+          <NavLink to="/projects">Projects</NavLink>
+        </NavItem>
+        <NavItem>
+          <NavLink to="/tasks">Tasks</NavLink>
+        </NavItem>
+      </div>
+
+      {/* User Actions */}
+      <div className="nav-section user-actions">
+        <NavItem>
+          <Button type="Ghost" leadingIcon={<Icon icon="Notifications" />}>
+            <Text>3</Text>
+          </Button>
+        </NavItem>
+        
+        <NavItem>
+          <Button type="Ghost" leadingIcon={<Icon icon="Search" />}>
+            Search
+          </Button>
+        </NavItem>
+        
+        <NavItem>
+          <ContextMenu
+            trigger={
+              <Button type="Ghost">
+                <Image src={user.avatar} alt={user.name} size="Small" />
+                <Text>{user.name}</Text>
+                <Icon icon="ExpandMore" />
+              </Button>
+            }
+          >
+            <NavLink to="/profile">Profile</NavLink>
+            <NavLink to="/settings">Settings</NavLink>
+            <NavLink to="/help">Help</NavLink>
+            <hr />
+            <NavLink to="/logout">Sign Out</NavLink>
+          </ContextMenu>
+        </NavItem>
+      </div>
+    </Nav>
+  );
+}
+```
+
+### Tab Navigation
+```tsx
+function TabNavExample() {
+  const [activeTab, setActiveTab] = useState('overview');
+
+  const tabs = [
+    { id: 'overview', label: 'Overview', icon: 'Dashboard' },
+    { id: 'activity', label: 'Activity', icon: 'Timeline' },
+    { id: 'settings', label: 'Settings', icon: 'Settings' },
+    { id: 'billing', label: 'Billing', icon: 'CreditCard' }
+  ];
+
+  return (
+    <Nav className="tab-nav" role="tablist" aria-label="Account sections">
+      {tabs.map(tab => (
+        <NavItem key={tab.id} role="none">
+          <NavLink
+            to={`/account/${tab.id}`}
+            role="tab"
+            aria-selected={activeTab === tab.id}
+            className={activeTab === tab.id ? 'active' : ''}
+            onClick={() => setActiveTab(tab.id)}
+            leadingIcon={<Icon icon={tab.icon} />}
+          >
+            {tab.label}
+          </NavLink>
+        </NavItem>
+      ))}
+    </Nav>
+  );
+}
+```
+
+### Breadcrumb Navigation
+```tsx
+function BreadcrumbNavExample() {
+  const breadcrumbs = [
+    { label: 'Home', to: '/' },
+    { label: 'Products', to: '/products' },
+    { label: 'Electronics', to: '/products/electronics' },
+    { label: 'Smartphones', to: '/products/electronics/smartphones' },
+    { label: 'iPhone 14', to: null } // Current page
+  ];
+
+  return (
+    <Nav className="breadcrumb-nav" aria-label="Breadcrumb navigation">
+      {breadcrumbs.map((crumb, index) => (
+        <NavItem key={index} className="breadcrumb-item">
+          {crumb.to ? (
+            <NavLink to={crumb.to}>{crumb.label}</NavLink>
+          ) : (
+            <Text className="current-page">{crumb.label}</Text>
+          )}
+          
+          {index < breadcrumbs.length - 1 && (
+            <Icon icon="ChevronRight" className="breadcrumb-separator" />
+          )}
+        </NavItem>
+      ))}
+    </Nav>
+  );
+}
+```
+
+### Pagination Navigation
+```tsx
+function PaginationNavExample() {
+  const [currentPage, setCurrentPage] = useState(1);
+  const totalPages = 10;
+  const maxVisiblePages = 5;
+
+  const getVisiblePages = () => {
+    const start = Math.max(1, currentPage - Math.floor(maxVisiblePages / 2));
+    const end = Math.min(totalPages, start + maxVisiblePages - 1);
+    return Array.from({ length: end - start + 1 }, (_, i) => start + i);
+  };
+
+  return (
+    <Nav className="pagination-nav" aria-label="Pagination navigation">
+      <NavItem>
+        <Button 
+          disabled={currentPage === 1}
+          onClick={() => setCurrentPage(1)}
+          aria-label="Go to first page"
+        >
+          <Icon icon="FirstPage" />
+        </Button>
+      </NavItem>
+      
+      <NavItem>
+        <Button 
+          disabled={currentPage === 1}
+          onClick={() => setCurrentPage(currentPage - 1)}
+          aria-label="Go to previous page"
+        >
+          <Icon icon="ChevronLeft" />
+        </Button>
+      </NavItem>
+
+      {getVisiblePages().map(page => (
+        <NavItem key={page}>
+          <Button
+            type={currentPage === page ? 'Filled' : 'Ghost'}
+            onClick={() => setCurrentPage(page)}
+            aria-label={`Go to page ${page}`}
+            aria-current={currentPage === page ? 'page' : undefined}
+          >
+            {page}
+          </Button>
+        </NavItem>
+      ))}
+
+      <NavItem>
+        <Button 
+          disabled={currentPage === totalPages}
+          onClick={() => setCurrentPage(currentPage + 1)}
+          aria-label="Go to next page"
+        >
+          <Icon icon="ChevronRight" />
+        </Button>
+      </NavItem>
+      
+      <NavItem>
+        <Button 
+          disabled={currentPage === totalPages}
+          onClick={() => setCurrentPage(totalPages)}
+          aria-label="Go to last page"
+        >
+          <Icon icon="LastPage" />
+        </Button>
+      </NavItem>
+    </Nav>
+  );
+}
+```
+
+### Custom Styled Navigation
+```tsx
+function CustomStyledNavExample() {
+  return (
+    <Nav 
+      className="custom-nav"
+      style={{
+        display: 'flex',
+        gap: '1rem',
+        padding: '1rem',
+        backgroundColor: 'var(--color-surface-elevated)',
+        borderRadius: '8px',
+        boxShadow: '0 2px 8px rgba(0, 0, 0, 0.1)'
+      }}
+      aria-label="Custom navigation"
+    >
+      <NavItem>
+        <NavLink 
+          to="/dashboard"
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: '0.5rem',
+            padding: '0.75rem 1rem',
+            borderRadius: '6px',
+            transition: 'all 0.2s ease'
+          }}
+          leadingIcon={<Icon icon="Dashboard" />}
+        >
+          Dashboard
+        </NavLink>
+      </NavItem>
+      
+      <NavItem>
+        <NavLink 
+          to="/analytics"
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: '0.5rem',
+            padding: '0.75rem 1rem',
+            borderRadius: '6px',
+            transition: 'all 0.2s ease'
+          }}
+          leadingIcon={<Icon icon="BarChart" />}
+        >
+          Analytics
+        </NavLink>
+      </NavItem>
+      
+      <NavItem>
+        <NavLink 
+          to="/reports"
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: '0.5rem',
+            padding: '0.75rem 1rem',
+            borderRadius: '6px',
+            transition: 'all 0.2s ease'
+          }}
+          leadingIcon={<Icon icon="Description" />}
+        >
+          Reports
+        </NavLink>
+      </NavItem>
+    </Nav>
+  );
+}
+```