@delightui/components 0.1.105 → 0.1.107

package/docs/components/molecules/Breadcrumbs.md

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