# Breadcrumbs Component

A navigation component that shows the user's current location in a hierarchical structure, helping users understand where they are and navigate back to previous levels.

## Features

- **Hierarchical Navigation**: Display path from root to current location
- **Clickable Items**: Navigate to any previous level (except current)
- **Custom Separators**: Configurable separator between breadcrumb items
- **Custom Data**: Associate any data with breadcrumb items
- **Click Handlers**: Custom logic for navigation actions
- **Responsive**: Adapts to container width

## Basic Usage

```svelte
<script>
import Breadcrumbs, { type Breadcrumb } from '@ticatec/uniface-element/Breadcrumbs';

const breadcrumbItems: Breadcrumb[] = [
  { label: 'Home', data: { path: '/' } },
  { label: 'Products', data: { path: '/products' } },
  { label: 'Electronics', data: { path: '/products/electronics' } },
  { label: 'Smartphones', data: { path: '/products/electronics/smartphones' } }
];

const handleItemClick = (data: any) => (event: MouseEvent) => {
  console.log('Navigate to:', data.path);
  // Handle navigation logic
};
</script>

<Breadcrumbs 
  items={breadcrumbItems} 
  onItemClick={handleItemClick} 
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `Breadcrumb[]` | `[]` | Array of breadcrumb items |
| `separator` | `string` | `"/"` | Separator character between items |
| `onItemClick` | `(item: any) => (event: MouseEvent) => void` | - | Click handler for breadcrumb items |
| `style` | `string` | `''` | Custom CSS styles |

## Breadcrumb Interface

```typescript
interface Breadcrumb {
  label: string;    // Display text for the breadcrumb
  data: any;        // Associated data (e.g., route, ID, etc.)
}
```

## Examples

### Basic File System Navigation

```svelte
<script>
const fileSystemPath = [
  { label: 'Documents', data: { path: '/documents' } },
  { label: 'Projects', data: { path: '/documents/projects' } },
  { label: 'MyApp', data: { path: '/documents/projects/myapp' } },
  { label: 'src', data: { path: '/documents/projects/myapp/src' } }
];

const navigateToFolder = (data: any) => (event: MouseEvent) => {
  window.location.href = data.path;
};
</script>

<Breadcrumbs 
  items={fileSystemPath}
  onItemClick={navigateToFolder}
  separator=" > "
/>
```

### E-commerce Category Navigation

```svelte
<script>
const categoryPath = [
  { label: 'All Categories', data: { categoryId: null } },
  { label: 'Electronics', data: { categoryId: 'electronics' } },
  { label: 'Computers', data: { categoryId: 'computers' } },
  { label: 'Laptops', data: { categoryId: 'laptops' } }
];

const goToCategory = (data: any) => (event: MouseEvent) => {
  if (data.categoryId) {
    router.push(`/category/${data.categoryId}`);
  } else {
    router.push('/categories');
  }
};
</script>

<Breadcrumbs 
  items={categoryPath}
  onItemClick={goToCategory}
  separator=" › "
/>
```

### Admin Panel Navigation

```svelte
<script>
const adminPath = [
  { label: 'Dashboard', data: { route: '/admin' } },
  { label: 'User Management', data: { route: '/admin/users' } },
  { label: 'Edit User', data: { route: '/admin/users/edit', userId: 123 } }
];

const navigateToAdminPage = (data: any) => (event: MouseEvent) => {
  // Custom navigation logic
  adminRouter.navigate(data.route);
};
</script>

<Breadcrumbs 
  items={adminPath}
  onItemClick={navigateToAdminPage}
/>
```

### Documentation Site

```svelte
<script>
const docsPath = [
  { label: 'Documentation', data: { section: 'home' } },
  { label: 'Components', data: { section: 'components' } },
  { label: 'Form Controls', data: { section: 'forms' } },
  { label: 'TextEditor', data: { section: 'texteditor' } }
];

const goToDocsSection = (data: any) => (event: MouseEvent) => {
  scrollToSection(data.section);
};
</script>

<Breadcrumbs 
  items={docsPath}
  onItemClick={goToDocsSection}
  separator=" • "
/>
```

### Custom Separator with Icons

```svelte
<script>
const projectPath = [
  { label: 'Workspace', data: { id: 'workspace' } },
  { label: 'Project Alpha', data: { id: 'project-alpha' } },
  { label: 'Settings', data: { id: 'settings' } }
];
</script>

<Breadcrumbs 
  items={projectPath}
  onItemClick={handleNavigation}
  separator=" 🔹 "
  style="font-size: 14px; color: #666;"
/>
```

### With Custom Styling

```svelte
<Breadcrumbs 
  items={breadcrumbs}
  onItemClick={navigate}
  separator=" / "
  style="
    background: #f8f9fa; 
    padding: 8px 16px; 
    border-radius: 4px; 
    font-size: 13px;
  "
/>
```

### Dynamic Breadcrumbs

```svelte
<script>
let currentPath = [];

// Build breadcrumbs based on current route
$: breadcrumbs = buildBreadcrumbs($page.url.pathname);

function buildBreadcrumbs(pathname) {
  const segments = pathname.split('/').filter(Boolean);
  const items = [{ label: 'Home', data: { path: '/' } }];
  
  let currentPath = '';
  segments.forEach(segment => {
    currentPath += `/${segment}`;
    items.push({
      label: formatSegment(segment),
      data: { path: currentPath }
    });
  });
  
  return items;
}

function formatSegment(segment) {
  return segment.charAt(0).toUpperCase() + segment.slice(1);
}

const navigateTo = (data) => (event) => {
  goto(data.path);
};
</script>

<Breadcrumbs 
  items={breadcrumbs}
  onItemClick={navigateTo}
/>
```

## Behavior

### Click Interaction
- All breadcrumb items except the last one are clickable
- The last item (current location) is not clickable and appears as plain text
- Click handlers receive the associated data object from the breadcrumb item

### Navigation Pattern
- Typically used for hierarchical navigation
- Helps users understand their current location
- Provides quick access to parent levels

## Styling

The component uses the following CSS classes:

- `.uniface-breadcrumbs` - Main container
- `.breadcrumb` - Individual breadcrumb item

### Example CSS

```css
.uniface-breadcrumbs {
  display: flex;
  align-items: center;
  flex-wrap: wrap;
  gap: 4px;
  font-size: 14px;
  color: #666;
}

.breadcrumb {
  cursor: pointer;
  color: #007acc;
  text-decoration: none;
}

.breadcrumb:hover {
  text-decoration: underline;
}

.breadcrumb:last-child {
  cursor: default;
  color: #333;
  font-weight: 500;
}

/* Responsive design */
@media (max-width: 768px) {
  .uniface-breadcrumbs {
    font-size: 12px;
  }
}
```

## Common Patterns

### Page Title Integration

```svelte
<div class="page-header">
  <Breadcrumbs items={breadcrumbs} onItemClick={navigate} />
  <h1>{currentPageTitle}</h1>
</div>
```

### With Loading State

```svelte
<script>
let loading = false;
let breadcrumbs = [];

const loadBreadcrumbs = async (pageId) => {
  loading = true;
  try {
    breadcrumbs = await fetchBreadcrumbs(pageId);
  } finally {
    loading = false;
  }
};
</script>

{#if loading}
  <div class="breadcrumb-skeleton">Loading...</div>
{:else}
  <Breadcrumbs items={breadcrumbs} onItemClick={navigate} />
{/if}
```

### Truncated Long Paths

```svelte
<script>
const MAX_ITEMS = 4;

$: displayItems = breadcrumbs.length > MAX_ITEMS
  ? [
      breadcrumbs[0],
      { label: '...', data: { truncated: true } },
      ...breadcrumbs.slice(-2)
    ]
  : breadcrumbs;

const handleClick = (data) => (event) => {
  if (data.truncated) {
    // Show dropdown with hidden items
    showFullPath = true;
    return;
  }
  navigate(data);
};
</script>

<Breadcrumbs 
  items={displayItems}
  onItemClick={handleClick}
/>
```

## Accessibility

- Use semantic navigation structure
- Provide clear visual distinction between clickable and non-clickable items
- Ensure adequate color contrast
- Consider ARIA labels for screen readers

```svelte
<nav aria-label="Breadcrumb navigation">
  <Breadcrumbs items={breadcrumbs} onItemClick={navigate} />
</nav>
```

## Integration with Routing

### SvelteKit Integration

```svelte
<script>
import { page } from '$app/stores';
import { goto } from '$app/navigation';

$: breadcrumbs = generateBreadcrumbs($page.route.id);

function generateBreadcrumbs(routeId) {
  // Generate breadcrumbs based on route structure
  return routeSegments.map(segment => ({
    label: segment.title,
    data: { path: segment.path }
  }));
}

const navigate = (data) => (event) => {
  goto(data.path);
};
</script>

<Breadcrumbs items={breadcrumbs} onItemClick={navigate} />
```

### React Router Integration

```javascript
// For reference - similar pattern can be adapted
const breadcrumbs = useBreadcrumbs(routes);
```

## Best Practices

1. **Clear Hierarchy**: Ensure breadcrumbs reflect a logical hierarchy
2. **Consistent Naming**: Use consistent labeling across similar pages
3. **Responsive Design**: Consider how breadcrumbs appear on mobile devices
4. **Performance**: Don't over-nest breadcrumb levels
5. **User Context**: Show relevant path based on user's entry point
6. **Skip Navigation**: Provide skip links for accessibility

## Mobile Considerations

For mobile devices, consider:

```css
@media (max-width: 480px) {
  .uniface-breadcrumbs {
    overflow-x: auto;
    white-space: nowrap;
  }
  
  /* Or show only parent and current */
  .breadcrumb:not(:nth-last-child(2)):not(:last-child) {
    display: none;
  }
}
```

## Testing

When testing breadcrumbs:

```javascript
// Test navigation
const breadcrumbs = [
  { label: 'Home', data: { path: '/' } },
  { label: 'Products', data: { path: '/products' } }
];

const mockNavigate = vi.fn();
render(Breadcrumbs, { 
  props: { items: breadcrumbs, onItemClick: mockNavigate } 
});

// Click first breadcrumb
fireEvent.click(screen.getByText('Home'));
expect(mockNavigate).toHaveBeenCalledWith({ path: '/' });
```