# Breadcrumbs

## Description

A navigation component that displays the current page's location within a hierarchical structure. Provides users with a clear path to understand their current position and navigate back to previous levels, enhancing website navigation and user experience.

## Aliases

- Breadcrumbs
- BreadcrumbTrail
- NavigationPath
- PathNavigation
- Breadcrumb Navigation

## Props Breakdown

**Extends:** Standalone interface (no HTML element inheritance)

| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `children` | `ReactNode` | - | Yes | The breadcrumb items to be displayed |
| `divider` | `ReactNode` | - | No | The divider element to separate breadcrumb items. Can be a string, icon, or custom React node |
| `className` | `string` | - | No | Additional CSS class names |

## Examples

### Basic Usage
```tsx
import { Breadcrumbs, Breadcrumb, Text } from '@delightui/components';

function BasicExample() {
  return (
    <Breadcrumbs>
      <Breadcrumb to="/home">
        <Text type="BodyMedium">Home</Text>
      </Breadcrumb>
      <Breadcrumb to="/products">
        <Text type="BodyMedium">Products</Text>
      </Breadcrumb>
      <Breadcrumb selected>
        <Text type="BodyMedium">Product Details</Text>
      </Breadcrumb>
    </Breadcrumbs>
  );
}
```

### Custom Divider
```tsx
function CustomDividerExample() {
  return (
    <div className="divider-examples">
      <Breadcrumbs divider="/">
        <Breadcrumb to="/home">
          <Text type="BodyMedium">Home</Text>
        </Breadcrumb>
        <Breadcrumb to="/docs">
          <Text type="BodyMedium">Documentation</Text>
        </Breadcrumb>
        <Breadcrumb selected>
          <Text type="BodyMedium">Components</Text>
        </Breadcrumb>
      </Breadcrumbs>

      <Breadcrumbs divider={<Icon icon="ArrowForward" size="Small" />}>
        <Breadcrumb to="/dashboard">
          <Text type="BodyMedium">Dashboard</Text>
        </Breadcrumb>
        <Breadcrumb to="/analytics">
          <Text type="BodyMedium">Analytics</Text>
        </Breadcrumb>
        <Breadcrumb selected>
          <Text type="BodyMedium">Reports</Text>
        </Breadcrumb>
      </Breadcrumbs>

      <Breadcrumbs divider="›">
        <Breadcrumb to="/admin">
          <Text type="BodyMedium">Admin</Text>
        </Breadcrumb>
        <Breadcrumb to="/users">
          <Text type="BodyMedium">Users</Text>
        </Breadcrumb>
        <Breadcrumb selected>
          <Text type="BodyMedium">User Management</Text>
        </Breadcrumb>
      </Breadcrumbs>
    </div>
  );
}
```

### E-commerce Navigation
```tsx
function EcommerceExample() {
  return (
    <Breadcrumbs divider="/" className="ecommerce-breadcrumbs">
      <Breadcrumb to="/">
        <Icon icon="Home" size="Small" />
        <Text type="BodyMedium">Home</Text>
      </Breadcrumb>
      
      <Breadcrumb to="/electronics">
        <Icon icon="Devices" size="Small" />
        <Text type="BodyMedium">Electronics</Text>
      </Breadcrumb>
      
      <Breadcrumb to="/electronics/smartphones">
        <Icon icon="Phone" size="Small" />
        <Text type="BodyMedium">Smartphones</Text>
      </Breadcrumb>
      
      <Breadcrumb to="/electronics/smartphones/apple">
        <Text type="BodyMedium">Apple</Text>
      </Breadcrumb>
      
      <Breadcrumb selected>
        <Text type="BodyMedium">iPhone 15 Pro</Text>
        <Chip size="Small" style="A">New</Chip>
      </Breadcrumb>
    </Breadcrumbs>
  );
}
```

### Admin Dashboard
```tsx
function AdminDashboardExample() {
  return (
    <Breadcrumbs 
      divider={<Icon icon="ChevronRight" size="Small" />}
      className="admin-breadcrumbs"
    >
      <Breadcrumb to="/admin">
        <Icon icon="Dashboard" size="Small" />
        <Text type="Heading6">Dashboard</Text>
      </Breadcrumb>
      
      <Breadcrumb to="/admin/users">
        <Icon icon="Users" size="Small" />
        <Text type="BodyMedium">User Management</Text>
      </Breadcrumb>
      
      <Breadcrumb to="/admin/users/roles">
        <Icon icon="Security" size="Small" />
        <Text type="BodyMedium">Roles & Permissions</Text>
      </Breadcrumb>
      
      <Breadcrumb selected>
        <Icon icon="Edit" size="Small" />
        <Text type="BodyMedium">Edit Role</Text>
        <Chip size="Small" style="B">Admin</Chip>
      </Breadcrumb>
    </Breadcrumbs>
  );
}
```

### File System Navigation
```tsx
function FileSystemExample() {
  const currentPath = '/Users/john/Documents/Projects/Website/src/components';
  const pathParts = currentPath.split('/').filter(Boolean);

  const BreadcrumbComponent = ({ part, index }) => {
    const isLast = index === pathParts.length - 1;
    const fullPath = '/' + pathParts.slice(0, index + 1).join('/');
    
    return (
      <Breadcrumb 
        to={isLast ? undefined : fullPath}
        selected={isLast}
      >
        <Icon icon="Folder" size="Small" />
        <Text type="BodyMedium">{part}</Text>
        {part === 'Projects' && (
          <Chip size="Small" style="A">Active</Chip>
        )}
      </Breadcrumb>
    );
  };

  return (
    <Breadcrumbs divider="/" className="file-system-breadcrumbs">
      <Breadcrumb to="/">
        <Icon icon="Computer" size="Small" />
        <Text type="BodyMedium">Root</Text>
      </Breadcrumb>
      
      <List
        data={pathParts.map((part, index) => ({ part, index }))}
        component={BreadcrumbComponent}
        keyExtractor={(item) => item.index}
      />
    </Breadcrumbs>
  );
}
```

### Multi-level Category Navigation
```tsx
function CategoryNavigationExample() {
  const categoryPath = [
    { label: 'All Categories', path: '/categories', icon: 'Category' },
    { label: 'Technology', path: '/categories/technology', icon: 'Computer' },
    { label: 'Web Development', path: '/categories/technology/web-dev', icon: 'Code' },
    { label: 'Frontend Frameworks', path: '/categories/technology/web-dev/frontend', icon: 'Web' },
    { label: 'React.js', selected: true, icon: 'Framework' }
  ];

  const CategoryBreadcrumbComponent = ({ label, path, icon, selected, index }) => (
    <Breadcrumb 
      to={path}
      selected={selected}
      navLinkType={index === 0 ? "Filled" : "Ghost"}
    >
      <Icon icon={icon} size="Small" />
      <Text 
        type={index === 0 ? "Heading6" : "BodyMedium"}
        className={`category-text level-${index}`}
      >
        {label}
      </Text>
      {selected && (
        <Chip size="Small" style="A">Current</Chip>
      )}
    </Breadcrumb>
  );

  return (
    <Breadcrumbs 
      divider={<Text type="BodySmall">•</Text>}
      className="category-breadcrumbs"
    >
      <List
        data={categoryPath.map((category, index) => ({ ...category, index }))}
        component={CategoryBreadcrumbComponent}
        keyExtractor={(category) => category.path || category.label}
      />
    </Breadcrumbs>
  );
}
```

### Blog Post Navigation
```tsx
function BlogNavigationExample() {
  return (
    <Breadcrumbs 
      divider={<Icon icon="ArrowForward" size="Small" />}
      className="blog-breadcrumbs"
    >
      <Breadcrumb to="/blog">
        <Icon icon="Article" size="Small" />
        <Text type="BodyMedium">Blog</Text>
      </Breadcrumb>
      
      <Breadcrumb to="/blog/web-development">
        <Text type="BodyMedium">Web Development</Text>
        <Chip size="Small" style="B">124 posts</Chip>
      </Breadcrumb>
      
      <Breadcrumb to="/blog/web-development/react">
        <Text type="BodyMedium">React</Text>
        <Chip size="Small" style="B">45 posts</Chip>
      </Breadcrumb>
      
      <Breadcrumb selected>
        <Text type="BodyMedium">Getting Started with React Hooks</Text>
        <div className="post-meta">
          <Chip size="Small" style="A">New</Chip>
          <Text type="BodySmall">5 min read</Text>
        </div>
      </Breadcrumb>
    </Breadcrumbs>
  );
}
```

### Project Management Navigation
```tsx
function ProjectManagementExample() {
  return (
    <Breadcrumbs 
      divider="→"
      className="project-breadcrumbs"
    >
      <Breadcrumb to="/projects">
        <Icon icon="Work" size="Small" />
        <Text type="Heading6">Projects</Text>
      </Breadcrumb>
      
      <Breadcrumb to="/projects/website-redesign">
        <div className="project-info">
          <Text type="BodyMedium">Website Redesign</Text>
          <div className="project-meta">
            <Chip size="Small" style="B">In Progress</Chip>
            <Text type="BodySmall">Due: Mar 15</Text>
          </div>
        </div>
      </Breadcrumb>
      
      <Breadcrumb to="/projects/website-redesign/tasks">
        <Icon icon="Task" size="Small" />
        <Text type="BodyMedium">Tasks</Text>
        <Chip size="Small" style="A">12 active</Chip>
      </Breadcrumb>
      
      <Breadcrumb selected>
        <Icon icon="BugReport" size="Small" />
        <Text type="BodyMedium">Bug Fixes</Text>
        <Chip size="Small" style="C">3 open</Chip>
      </Breadcrumb>
    </Breadcrumbs>
  );
}
```

### Responsive Breadcrumbs
```tsx
function ResponsiveBreadcrumbsExample() {
  const [collapsed, setCollapsed] = useState(true);
  
  const allBreadcrumbs = [
    { label: 'Home', path: '/', icon: 'Home' },
    { label: 'Products', path: '/products', icon: 'Inventory' },
    { label: 'Electronics', path: '/products/electronics', icon: 'Devices' },
    { label: 'Computers', path: '/products/electronics/computers', icon: 'Computer' },
    { label: 'Laptops', path: '/products/electronics/computers/laptops', icon: 'Laptop' },
    { label: 'Gaming', path: '/products/electronics/computers/laptops/gaming', icon: 'Games' },
    { label: 'High Performance', selected: true, icon: 'Speed' }
  ];

  const visibleBreadcrumbs = collapsed 
    ? [allBreadcrumbs[0], ...allBreadcrumbs.slice(-2)]
    : allBreadcrumbs;

  return (
    <div className="responsive-breadcrumbs-container">
      <Breadcrumbs 
        divider="/"
        className="responsive-breadcrumbs"
      >
        {collapsed && allBreadcrumbs.length > 3 && (
          <>
            <Breadcrumb to={allBreadcrumbs[0].path}>
              <Icon icon={allBreadcrumbs[0].icon} size="Small" />
              <Text type="BodyMedium">{allBreadcrumbs[0].label}</Text>
            </Breadcrumb>
            
            <Breadcrumb 
              onClick={() => setCollapsed(false)}
              className="breadcrumb-ellipsis"
            >
              <Icon icon="MoreHorizontal" size="Small" />
              <Text type="BodyMedium">...</Text>
            </Breadcrumb>
          </>
        )}
        
        <List
          data={collapsed ? allBreadcrumbs.slice(-2) : allBreadcrumbs}
          component={({ label, path, icon, selected }) => (
            <Breadcrumb 
              to={selected ? undefined : path}
              selected={selected}
            >
              <Icon icon={icon} size="Small" />
              <Text type="BodyMedium">{label}</Text>
            </Breadcrumb>
          )}
          keyExtractor={(item) => item.path || item.label}
        />
      </Breadcrumbs>
      
      {!collapsed && (
        <Button 
          size="Small" 
          type="Ghost" 
          onClick={() => setCollapsed(true)}
          className="collapse-button"
        >
          <Icon icon="ExpandLess" size="Small" />
          <Text type="BodySmall">Collapse</Text>
        </Button>
      )}
    </div>
  );
}
```

### Interactive Breadcrumbs with Actions
```tsx
function InteractiveBreadcrumbsExample() {
  const [bookmarked, setBookmarked] = useState(false);
  const [showActions, setShowActions] = useState(false);

  return (
    <div className="interactive-breadcrumbs-container">
      <Breadcrumbs 
        divider={<Icon icon="ChevronRight" size="Small" />}
        className="interactive-breadcrumbs"
      >
        <Breadcrumb to="/workspace">
          <Icon icon="Work" size="Small" />
          <Text type="BodyMedium">Workspace</Text>
        </Breadcrumb>
        
        <Breadcrumb to="/workspace/projects">
          <Icon icon="Folder" size="Small" />
          <Text type="BodyMedium">Projects</Text>
        </Breadcrumb>
        
        <Breadcrumb 
          to="/workspace/projects/current"
          onMouseEnter={() => setShowActions(true)}
          onMouseLeave={() => setShowActions(false)}
        >
          <Icon icon="FolderOpen" size="Small" />
          <Text type="BodyMedium">Current Project</Text>
          {showActions && (
            <div className="breadcrumb-actions">
              <IconButton 
                icon={bookmarked ? "BookmarkFilled" : "Bookmark"}
                size="Small"
                onClick={() => setBookmarked(!bookmarked)}
              />
              <IconButton icon="Share" size="Small" />
              <IconButton icon="MoreVertical" size="Small" />
            </div>
          )}
        </Breadcrumb>
        
        <Breadcrumb selected>
          <Icon icon="InsertDriveFile" size="Small" />
          <Text type="BodyMedium">README.md</Text>
          <div className="file-meta">
            <Chip size="Small" style="B">Modified</Chip>
            <Text type="BodySmall">2h ago</Text>
          </div>
        </Breadcrumb>
      </Breadcrumbs>
    </div>
  );
}
```

### Search Results Navigation
```tsx
function SearchResultsExample() {
  const searchQuery = "react components";
  
  return (
    <Breadcrumbs 
      divider="•"
      className="search-breadcrumbs"
    >
      <Breadcrumb to="/search">
        <Icon icon="Search" size="Small" />
        <Text type="BodyMedium">Search</Text>
      </Breadcrumb>
      
      <Breadcrumb to={`/search?q=${encodeURIComponent(searchQuery)}`}>
        <Text type="BodyMedium">"{searchQuery}"</Text>
        <Chip size="Small" style="A">1,247 results</Chip>
      </Breadcrumb>
      
      <Breadcrumb to={`/search?q=${encodeURIComponent(searchQuery)}&category=tutorials`}>
        <Icon icon="School" size="Small" />
        <Text type="BodyMedium">Tutorials</Text>
        <Chip size="Small" style="B">89 items</Chip>
      </Breadcrumb>
      
      <Breadcrumb selected>
        <Icon icon="Article" size="Small" />
        <Text type="BodyMedium">Advanced React Patterns</Text>
        <div className="result-meta">
          <Icon icon="Star" size="Small" />
          <Text type="BodySmall">4.8</Text>
        </div>
      </Breadcrumb>
    </Breadcrumbs>
  );
}
```