@delightui/components 0.1.105 → 0.1.107

package/docs/components/molecules/NavItem.md

@@ -0,0 +1,572 @@
+# NavItem
+
+## Description
+
+A navigation item component that serves as a semantic wrapper for individual navigation elements. Provides proper list item structure for navigation menus and ensures accessibility compliance when used within navigation containers.
+
+## Aliases
+
+- NavItem
+- NavigationItem
+- NavListItem
+- MenuItem
+- NavElement
+
+## Props Breakdown
+
+**Extends:** `LiHTMLAttributes<HTMLElement>`
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `children` | `ReactNode` | - | Yes | Content to render inside the navigation item |
+| `className` | `string` | - | No | Additional CSS class names for custom styling |
+| `role` | `string` | `'menuitem'` | No | ARIA role for accessibility |
+| `tabIndex` | `number` | - | No | Tab order for keyboard navigation |
+
+Plus all standard HTML list item attributes (`id`, `style`, `onClick`, etc.).
+
+## Examples
+
+### Basic Usage
+```tsx
+import { Nav, NavItem, NavLink } from '@delightui/components';
+
+function BasicExample() {
+  return (
+    <Nav>
+      <NavItem>
+        <NavLink to="/home">Home</NavLink>
+      </NavItem>
+      <NavItem>
+        <NavLink to="/about">About</NavLink>
+      </NavItem>
+      <NavItem>
+        <NavLink to="/contact">Contact</NavLink>
+      </NavItem>
+    </Nav>
+  );
+}
+```
+
+### Navigation Items with Icons
+```tsx
+function IconNavItemsExample() {
+  return (
+    <Nav className="icon-nav">
+      <NavItem>
+        <NavLink to="/dashboard" leadingIcon={<Icon icon="Dashboard" />}>
+          Dashboard
+        </NavLink>
+      </NavItem>
+      
+      <NavItem>
+        <NavLink to="/projects" leadingIcon={<Icon icon="Folder" />}>
+          Projects
+        </NavLink>
+      </NavItem>
+      
+      <NavItem>
+        <NavLink to="/team" leadingIcon={<Icon icon="People" />}>
+          Team Members
+        </NavLink>
+      </NavItem>
+      
+      <NavItem>
+        <NavLink 
+          to="/settings" 
+          leadingIcon={<Icon icon="Settings" />}
+          trailingIcon={<Icon icon="ChevronRight" />}
+        >
+          Settings
+        </NavLink>
+      </NavItem>
+    </Nav>
+  );
+}
+```
+
+### Interactive Navigation Items
+```tsx
+function InteractiveNavItemsExample() {
+  const [activeItem, setActiveItem] = useState('dashboard');
+
+  return (
+    <Nav>
+      <NavItem 
+        className={activeItem === 'dashboard' ? 'active' : ''}
+        onClick={() => setActiveItem('dashboard')}
+      >
+        <NavLink to="/dashboard">
+          <Icon icon="Dashboard" />
+          <Text>Dashboard</Text>
+        </NavLink>
+      </NavItem>
+      
+      <NavItem 
+        className={activeItem === 'analytics' ? 'active' : ''}
+        onClick={() => setActiveItem('analytics')}
+      >
+        <NavLink to="/analytics">
+          <Icon icon="BarChart" />
+          <Text>Analytics</Text>
+          <Chip size="Small" style="Success">New</Chip>
+        </NavLink>
+      </NavItem>
+      
+      <NavItem 
+        className={activeItem === 'reports' ? 'active' : ''}
+        onClick={() => setActiveItem('reports')}
+      >
+        <NavLink to="/reports">
+          <Icon icon="Description" />
+          <Text>Reports</Text>
+          <Text type="BodySmall" className="item-count">12</Text>
+        </NavLink>
+      </NavItem>
+    </Nav>
+  );
+}
+```
+
+### Navigation Items with Buttons
+```tsx
+function ButtonNavItemsExample() {
+  const [notifications, setNotifications] = useState(3);
+
+  return (
+    <Nav className="header-nav">
+      <NavItem>
+        <Button type="Ghost" leadingIcon={<Icon icon="Search" />}>
+          Search
+        </Button>
+      </NavItem>
+      
+      <NavItem>
+        <Button 
+          type="Ghost" 
+          leadingIcon={<Icon icon="Notifications" />}
+          trailingIcon={
+            notifications > 0 && (
+              <Chip size="Small" style="Danger">
+                {notifications}
+              </Chip>
+            )
+          }
+        >
+          Notifications
+        </Button>
+      </NavItem>
+      
+      <NavItem>
+        <Button type="Ghost" leadingIcon={<Icon icon="Help" />}>
+          Help
+        </Button>
+      </NavItem>
+      
+      <NavItem>
+        <Button type="Filled" leadingIcon={<Icon icon="Add" />}>
+          New Project
+        </Button>
+      </NavItem>
+    </Nav>
+  );
+}
+```
+
+### Disabled Navigation Items
+```tsx
+function DisabledNavItemsExample() {
+  const [userPermissions, setUserPermissions] = useState({
+    canViewReports: false,
+    canManageUsers: false,
+    canAccessSettings: true
+  });
+
+  return (
+    <Nav>
+      <NavItem>
+        <NavLink to="/dashboard">Dashboard</NavLink>
+      </NavItem>
+      
+      <NavItem className={!userPermissions.canViewReports ? 'disabled' : ''}>
+        <NavLink 
+          to="/reports"
+          style={{
+            opacity: userPermissions.canViewReports ? 1 : 0.5,
+            pointerEvents: userPermissions.canViewReports ? 'auto' : 'none'
+          }}
+        >
+          Reports
+          {!userPermissions.canViewReports && (
+            <Icon icon="Lock" className="disabled-icon" />
+          )}
+        </NavLink>
+      </NavItem>
+      
+      <NavItem className={!userPermissions.canManageUsers ? 'disabled' : ''}>
+        <NavLink 
+          to="/users"
+          style={{
+            opacity: userPermissions.canManageUsers ? 1 : 0.5,
+            pointerEvents: userPermissions.canManageUsers ? 'auto' : 'none'
+          }}
+        >
+          User Management
+          {!userPermissions.canManageUsers && (
+            <Icon icon="Lock" className="disabled-icon" />
+          )}
+        </NavLink>
+      </NavItem>
+      
+      <NavItem>
+        <NavLink to="/settings">Settings</NavLink>
+      </NavItem>
+    </Nav>
+  );
+}
+```
+
+### Navigation Items with Context Menus
+```tsx
+function ContextMenuNavItemsExample() {
+  return (
+    <Nav>
+      <NavItem>
+        <NavLink to="/dashboard">Dashboard</NavLink>
+      </NavItem>
+      
+      <NavItem>
+        <ContextMenu
+          trigger={
+            <NavLink to="/projects">
+              Projects
+              <Icon icon="ExpandMore" />
+            </NavLink>
+          }
+        >
+          <NavLink to="/projects/active">Active Projects</NavLink>
+          <NavLink to="/projects/completed">Completed</NavLink>
+          <NavLink to="/projects/archived">Archived</NavLink>
+          <hr />
+          <NavLink to="/projects/new">Create New Project</NavLink>
+        </ContextMenu>
+      </NavItem>
+      
+      <NavItem>
+        <ContextMenu
+          trigger={
+            <NavLink to="/team">
+              Team
+              <Icon icon="ExpandMore" />
+            </NavLink>
+          }
+        >
+          <NavLink to="/team/members">Team Members</NavLink>
+          <NavLink to="/team/roles">Roles & Permissions</NavLink>
+          <NavLink to="/team/invitations">Pending Invitations</NavLink>
+          <hr />
+          <NavLink to="/team/invite">Invite Member</NavLink>
+        </ContextMenu>
+      </NavItem>
+    </Nav>
+  );
+}
+```
+
+### Grouped Navigation Items
+```tsx
+function GroupedNavItemsExample() {
+  return (
+    <Nav className="grouped-nav">
+      <div className="nav-group">
+        <Text type="BodySmall" className="group-label">MAIN</Text>
+        
+        <NavItem>
+          <NavLink to="/dashboard" leadingIcon={<Icon icon="Dashboard" />}>
+            Dashboard
+          </NavLink>
+        </NavItem>
+        
+        <NavItem>
+          <NavLink to="/projects" leadingIcon={<Icon icon="Folder" />}>
+            Projects
+          </NavLink>
+        </NavItem>
+        
+        <NavItem>
+          <NavLink to="/tasks" leadingIcon={<Icon icon="CheckBox" />}>
+            Tasks
+          </NavLink>
+        </NavItem>
+      </div>
+
+      <div className="nav-group">
+        <Text type="BodySmall" className="group-label">MANAGEMENT</Text>
+        
+        <NavItem>
+          <NavLink to="/team" leadingIcon={<Icon icon="People" />}>
+            Team
+          </NavLink>
+        </NavItem>
+        
+        <NavItem>
+          <NavLink to="/analytics" leadingIcon={<Icon icon="Analytics" />}>
+            Analytics
+          </NavLink>
+        </NavItem>
+        
+        <NavItem>
+          <NavLink to="/reports" leadingIcon={<Icon icon="Description" />}>
+            Reports
+          </NavLink>
+        </NavItem>
+      </div>
+
+      <div className="nav-group">
+        <Text type="BodySmall" className="group-label">SETTINGS</Text>
+        
+        <NavItem>
+          <NavLink to="/preferences" leadingIcon={<Icon icon="Settings" />}>
+            Preferences
+          </NavLink>
+        </NavItem>
+        
+        <NavItem>
+          <NavLink to="/billing" leadingIcon={<Icon icon="CreditCard" />}>
+            Billing
+          </NavLink>
+        </NavItem>
+      </div>
+    </Nav>
+  );
+}
+```
+
+### Navigation Items with Custom Content
+```tsx
+function CustomContentNavItemsExample() {
+  const [unreadCount, setUnreadCount] = useState(5);
+  const [storageUsed, setStorageUsed] = useState(78);
+
+  return (
+    <Nav className="custom-content-nav">
+      <NavItem>
+        <NavLink to="/inbox" className="inbox-item">
+          <div className="item-content">
+            <div className="item-header">
+              <Icon icon="Mail" />
+              <Text>Inbox</Text>
+            </div>
+            {unreadCount > 0 && (
+              <Chip size="Small" style="Primary">
+                {unreadCount}
+              </Chip>
+            )}
+          </div>
+        </NavLink>
+      </NavItem>
+      
+      <NavItem>
+        <NavLink to="/storage" className="storage-item">
+          <div className="item-content">
+            <div className="item-header">
+              <Icon icon="Storage" />
+              <Text>Storage</Text>
+            </div>
+            <div className="storage-info">
+              <ProgressBar value={storageUsed} max={100} size="Small" />
+              <Text type="BodySmall">{storageUsed}% used</Text>
+            </div>
+          </div>
+        </NavLink>
+      </NavItem>
+      
+      <NavItem>
+        <NavLink to="/activity" className="activity-item">
+          <div className="item-content">
+            <div className="item-header">
+              <Icon icon="Timeline" />
+              <Text>Recent Activity</Text>
+            </div>
+            <Text type="BodySmall" className="activity-time">
+              2 minutes ago
+            </Text>
+          </div>
+        </NavLink>
+      </NavItem>
+    </Nav>
+  );
+}
+```
+
+### Mobile Navigation Items
+```tsx
+function MobileNavItemsExample() {
+  const [isMenuOpen, setIsMenuOpen] = useState(false);
+
+  return (
+    <>
+      <Button 
+        className="mobile-menu-toggle"
+        onClick={() => setIsMenuOpen(!isMenuOpen)}
+      >
+        <Icon icon="Menu" />
+      </Button>
+
+      <Nav className={`mobile-nav ${isMenuOpen ? 'open' : ''}`}>
+        <NavItem className="mobile-nav-item">
+          <NavLink 
+            to="/home" 
+            onClick={() => setIsMenuOpen(false)}
+            className="mobile-nav-link"
+          >
+            <Icon icon="Home" />
+            <Text>Home</Text>
+          </NavLink>
+        </NavItem>
+        
+        <NavItem className="mobile-nav-item">
+          <NavLink 
+            to="/profile" 
+            onClick={() => setIsMenuOpen(false)}
+            className="mobile-nav-link"
+          >
+            <Icon icon="Person" />
+            <Text>Profile</Text>
+          </NavLink>
+        </NavItem>
+        
+        <NavItem className="mobile-nav-item">
+          <NavLink 
+            to="/messages" 
+            onClick={() => setIsMenuOpen(false)}
+            className="mobile-nav-link"
+          >
+            <Icon icon="Message" />
+            <Text>Messages</Text>
+            <Chip size="Small" style="Danger">3</Chip>
+          </NavLink>
+        </NavItem>
+        
+        <NavItem className="mobile-nav-item">
+          <NavLink 
+            to="/settings" 
+            onClick={() => setIsMenuOpen(false)}
+            className="mobile-nav-link"
+          >
+            <Icon icon="Settings" />
+            <Text>Settings</Text>
+          </NavLink>
+        </NavItem>
+      </Nav>
+    </>
+  );
+}
+```
+
+### Navigation Items with Keyboard Navigation
+```tsx
+function KeyboardNavItemsExample() {
+  const [focusedIndex, setFocusedIndex] = useState(0);
+  const navItems = [
+    { to: '/dashboard', label: 'Dashboard', icon: 'Dashboard' },
+    { to: '/projects', label: 'Projects', icon: 'Folder' },
+    { to: '/team', label: 'Team', icon: 'People' },
+    { to: '/settings', label: 'Settings', icon: 'Settings' }
+  ];
+
+  const handleKeyDown = (event, index) => {
+    switch (event.key) {
+      case 'ArrowDown':
+        event.preventDefault();
+        setFocusedIndex((prev) => (prev + 1) % navItems.length);
+        break;
+      case 'ArrowUp':
+        event.preventDefault();
+        setFocusedIndex((prev) => (prev - 1 + navItems.length) % navItems.length);
+        break;
+      case 'Home':
+        event.preventDefault();
+        setFocusedIndex(0);
+        break;
+      case 'End':
+        event.preventDefault();
+        setFocusedIndex(navItems.length - 1);
+        break;
+    }
+  };
+
+  return (
+    <Nav className="keyboard-nav" role="menubar">
+      {navItems.map((item, index) => (
+        <NavItem 
+          key={item.to}
+          role="none"
+          className={focusedIndex === index ? 'focused' : ''}
+        >
+          <NavLink
+            to={item.to}
+            role="menuitem"
+            tabIndex={focusedIndex === index ? 0 : -1}
+            onKeyDown={(e) => handleKeyDown(e, index)}
+            onFocus={() => setFocusedIndex(index)}
+            leadingIcon={<Icon icon={item.icon} />}
+          >
+            {item.label}
+          </NavLink>
+        </NavItem>
+      ))}
+    </Nav>
+  );
+}
+```
+
+### Dynamic Navigation Items
+```tsx
+function DynamicNavItemsExample() {
+  const [userRole, setUserRole] = useState('admin');
+  const [navigationItems, setNavigationItems] = useState([]);
+
+  useEffect(() => {
+    const baseItems = [
+      { id: 'dashboard', label: 'Dashboard', to: '/dashboard', icon: 'Dashboard', roles: ['user', 'admin', 'moderator'] },
+      { id: 'projects', label: 'Projects', to: '/projects', icon: 'Folder', roles: ['user', 'admin', 'moderator'] },
+      { id: 'analytics', label: 'Analytics', to: '/analytics', icon: 'Analytics', roles: ['admin', 'moderator'] },
+      { id: 'users', label: 'User Management', to: '/users', icon: 'People', roles: ['admin'] },
+      { id: 'settings', label: 'Settings', to: '/settings', icon: 'Settings', roles: ['admin'] }
+    ];
+
+    const filteredItems = baseItems.filter(item => 
+      item.roles.includes(userRole)
+    );
+
+    setNavigationItems(filteredItems);
+  }, [userRole]);
+
+  return (
+    <div className="dynamic-nav-example">
+      <div className="role-selector">
+        <Text>Current Role:</Text>
+        <Select value={userRole} onValueChange={setUserRole}>
+          <Option value="user">User</Option>
+          <Option value="moderator">Moderator</Option>
+          <Option value="admin">Admin</Option>
+        </Select>
+      </div>
+
+      <Nav className="dynamic-nav">
+        {navigationItems.map(item => (
+          <NavItem key={item.id}>
+            <NavLink 
+              to={item.to}
+              leadingIcon={<Icon icon={item.icon} />}
+            >
+              {item.label}
+            </NavLink>
+          </NavItem>
+        ))}
+      </Nav>
+    </div>
+  );
+}
+```